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 Google Tài liệu.
Tóm tắt dự án
- Tổ chức nguồn mở:
- Nền tảng Linux
- Người viết nội dung kỹ thuật:
- boron
- Tên dự án:
- Sửa đổi cách lưu trữ và tạo tài liệu, Điều chỉnh cấu trúc trang bắt đầu và hướng dẫn cho nhà phát triển.
- Thời lượng dự án:
- Thời gian tiêu chuẩn (3 tháng)
Mô tả dự án
Bả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 sản phẩm hoặc dịch vụ. Tài liệu hay là tài liệu rất quan trọng vì nó mang đến một không gian cho 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ũng như giải quyết các vấn đề thường gặp khi dùng phần mềm. Điều này cũng làm giảm chi phí hỗ trợ và là một phần trong đặc trưng của 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 tính lành mạnh của sản phẩm và nhóm nhà phát triển.
Nếu không có tài liệu xác minh, người dùng có thể không biết cách thực hiện những việc trên một cách hiệu quả. Tài liệu có thể đóng vai trò then chốt trong việc đảm bảo thành công của sản phẩm bởi vì khả năng truyền thông tốt sẽ luôn là và sẽ luôn 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ỉ bao gồm thông tin giao tiếp đó và đặt chúng trong một khuôn khổ có thể quản lý mà mọi người đều có thể truy cập để thành công.
Trong một tổ chức như AGL, mỗi trang web tài liệu đều cần có một quy trình xây dựng và lưu trữ quy trình công việc hiệu quả, 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) 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 vô cùng phức tạp và tốn thời gian.
Trạng thái hiện tại :
- Trang web của tài liệu AGL dựa trên 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 từng nguồn dưới dạng đánh dấu bằng cách sử dụng công cụ của dự án cordova.
- Từ đó, bạn sẽ 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 của Jekyll.
- Tài liệu công cụ [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-sources [https://github.com/automotive-grade-linux/docs-sources] : Nguồn (markdowns [https://github.com/automotive-grade-linux/docs-sources/tree/master/docs]) cho các tài liệu, hướng dẫn chung.
- Tài liệu-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] : Kho lưu trữ các 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ụ (script) có trong docs-tools [https://github.com/automotive-grade-linux/docs-tools] đảm nhận việc thu thập và tạo mẫu cho tất cả các tệp đánh dấu theo phương thức tìm nạp.yml nằm trong docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate].
- Quy trình làm việc 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/1OSwkVWFcsajgCOnjtdPf42EIfpidUJ0U/view?usp=sharing]
- Phần_version.yml chứa các đường liên kết đến tất cả tệp yaml của sách, nó sẽ tiếp tục tìm nạp tất cả tệp yaml của sách từ kho lưu trữ từ xa tới 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 đánh dấu của bạn từ kho lưu trữ từ xa.
- Ngay sau khi tất cả các tệp đánh dấu được tìm nạp, quy trình công cụ để 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.
- Quá 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 cộng tác viên mới. Quy trình quy trình làm việc này (xây dựng và lưu trữ) có thể được đơn giản hoá và hợp lý hơn để nhà phát triển tập trung vào phần tài liệu hơn là duy trì quy trình tạo và triển khai tài liệu.