Trang này chứa thông tin chi tiết về một dự án viết kỹ thuật được chấp nhận cho Phần tài liệu của Google.
Tóm tắt dự án
- Tổ chức nguồn mở:
- The Linux Foundation
- Tác giả kỹ thuật:
- trâu
- Tên dự án:
- Sửa đổi nội dung lưu trữ và tạo tài liệu, cũng như Tái cấu trúc các trang bắt đầu và hướng dẫn 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 chất lượng rất quan trọng vì nó cung cấp cho người dùng một phương tiện để tìm hiểu cách sử dụng phần mềm, các tính năng, mẹo và thủ thuật cũng như giải quyết các vấn đề thường gặp khi sử dụng phần mềm. Điều này cũng giúp giảm chi phí hỗ trợ và là một phần của danh tính công ty và nguồn mở của sản phẩm : một 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 hoạt động tốt.
Nếu không có tài liệu thích hợp, người dùng có thể không biết cách thực hiện những việc trên sao cho hiệu quả. Tài liệu có thể đóng một vai trò then chốt trong việc đảm bảo sự thành công của sản phẩm bởi vì giao tiếp hiệu quả là trọng tâm của bất kỳ doanh nghiệp hoặc sản phẩm nào. Ngoài ra, một tài liệu tuyệt vời chỉ cần sự giao tiếp đó và đặt nó vào một khuôn khổ dễ quản lý mà ai cũng có thể tiếp cận để thành công.
Mỗi trang web tài liệu đều cần có quy trình làm việc tốt để tạo và lưu trữ, 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 phân tán trên nhiều kho lưu trữ, khiến việc duy trì và cập nhật các tệp này 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 markdown được tìm nạp từ nhiều kho lưu trữ.
- Hiện tại, các trang tài liệu được lưu trữ trong từng nguồn dưới dạng Markdown bằng công cụ của dự án Wi-Fi.
- Điều này dẫn đến việc thiết lập 4 kho lưu trữ cho quá 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 trang web kỹ thuật từ các tệp Markdown.
- Tài liệu nguồn [https://github.com/automotive-grade-linux/docs-sources] : Nguồn (markdown [https://github.com/automotive-grade-linux/docs-sources/tree/master/docs]) cho tài liệu chung, hướng dẫn.
- Docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] : Triển khai kho lưu trữ trang GitHub 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ẽ thu thập và tạo mẫu tất 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 của việc tạo trang web tài liệu agl : current_workflow [https://drive.google.com/file/d/1OSwkVWFcsajgCOjbtdPf42EIfpidUJ0U/view?usp=sharing]
- Phần_version.yml chứa các đường liên kết đến tất cả các tệp yaml của sách, phần này tiếp tục tìm nạp tất cả các tệp yaml của sách từ các kho lưu trữ từ xa đến 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 từ kho lưu trữ từ xa.
- Ngay khi tất 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] được triển khai tương ứng.
- Quy trình duy trì quy trình hiện tại 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 (của việc tạo và lưu trữ) có thể được đơn giản hoá và tinh giản hơn nhiều để các 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.