Trang này chứa thông tin chi tiết về một dự án viết tài liệu kỹ thuật được chấp nhận cho Google Season of Docs.
Tóm tắt dự án
- Tổ chức nguồn mở:
- The Linux Foundation
- Chuyên viên viết tài liệu kỹ thuật:
- bo
- Tên dự án:
- Làm lại quy trình lưu trữ và tạo tài liệu, đồng thời tái cấu trúc các trang bắt đầu và hướng dẫn dành cho nhà phát triển.
- Thời lượng dự án:
- Thời hạn tiêu chuẩn (3 tháng)
Mô tả dự án
Tóm tắt :
Tài liệu được thiết kế để hỗ trợ người dùng cuối và nhà phát triển sử dụng một sản phẩm hoặc dịch vụ. Tài liệu đầy đủ là rất quan trọng vì đây là cách để người dùng tìm hiểu cách sử dụng phần mềm, các tính năng, mẹo, thủ thuật và cả cách giải quyết các vấn đề thường gặp khi sử dụng phần mềm. Việc này cũng giúp giảm chi phí hỗ trợ và là một phần trong bản sắc doanh nghiệp và nguồn mở của sản phẩm : tài liệu tốt là dấu hiệu cho thấy sản phẩm và nhóm nhà phát triển đang hoạt động hiệu quả.
Nếu không có tài liệu phù hợp, người dùng có thể không biết cách thực hiện những việc nêu trên một cách hiệu quả. Tài liệu có thể đóng vai trò quan trọng trong việc đảm bảo sự thành công của một sản phẩm vì khả năng giao tiếp hiệu quả luôn là yếu tố cốt lõi của mọi doanh nghiệp hoặc sản phẩm. Tài liệu hiệu quả chỉ cần có khả năng giao tiếp đó và đưa vào một khung hình có thể quản lý mà mọi người có thể truy cập để đạt được thành công.
Mọi trang web tài liệu đều cần một quy trình xây dựng và lưu trữ hiệu quả. Trong một tổ chức như AGL, với nhiều phiên bản và rất nhiều tài liệu chi tiết, các tệp tài liệu (markdown) được trải rộng trên nhiều kho lưu trữ, khiến nhiệm vụ duy trì và cập nhật chúng trở nên vô cùng phức tạp và tốn thời gian.
Trạng thái hiện tại :
- Trang web tài liệu AGL dựa trên một tập hợp các tệp đánh dấu được tìm nạp từ nhiều kho lưu trữ.
- Các trang tài liệu hiện được lưu trữ trong các nguồn riêng lẻ dưới dạng markdown bằng cách sử dụng công cụ của dự án cordova.
- Điều này dẫn đến việc thiết lập 4 kho lưu trữ cho quy trình tạo và lưu trữ tài liệu :
- Docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] : Chứa mẫu trang web Jekyll.
- Docs-tools [https://github.com/automotive-grade-linux/docs-tools] : Chứa các công cụ để tự động tạo một trang web kỹ thuật từ các tệp Markdown.
- Docs-sources [https://github.com/automotive-grade-linux/docs-sources] : Nguồn (markdown [https://github.com/automotive-grade-linux/docs-sources/tree/master/docs]) cho các tài liệu và hướng dẫn chung.
- Docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] : Kho lưu trữ trang GitHub đã triển khai cho trang web tài liệu [https://gist.github.com/growupboron/docs.automotivelinux.org].
- Một công cụ (tập lệnh) có trong docs-tools [https://github.com/automotive-grade-linux/docs-tools] sẽ chịu trách nhiệm thu thập và tạo mẫu cho tất cả các tệp markdown theo fetched_files.yml nằm trong docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate].
- Quy trình hiện tại để tạo trang web tài liệu agl : current_workflow [https://drive.google.com/file/d/1OSwkVWFcsajgCOjbtdPf42EIfpidUJ0U/view?usp=sharing]
- section_version.yml chứa các đường liên kết đến tất cả các tệp yaml của sách, sau đó sẽ tìm nạp tất cả các tệp yaml của sách từ kho lưu trữ từ xa vào docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate]. Các tệp yaml của sách chứa tất cả URL đến các tệp markdown của bạn trong kho lưu trữ từ xa.
- Ngay khi tất cả các tệp markdown được tìm nạp, các công cụ sẽ xử lý để tạo trang web tài liệu AGL trong docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] và được triển khai tương ứng.
- Quy trình hiện tại để duy trì quy trình không thân thiện với người dùng và nhà phát triển, đặc biệt là đối với những người đóng góp mới. Quy trình công việc này (xây dựng và lưu trữ) có thể được đơn giản hoá và tinh giản hơn nhiều để nhà phát triển tập trung vào phần tài liệu thay vì duy trì quy trình tạo và triển khai tài liệu.