Trang này chứa thông tin chi tiết về một dự án viết nội dung kỹ thuật đã được chấp nhận tham gia Google Season of Docs.
Tóm tắt dự án
- Tổ chức nguồn mở:
- Kolibri
- Người viết nội dung kỹ thuật:
- StephDix
- Tên dự án:
- Quy ước về quy trình làm việc và phong cách tài liệu về hệ sinh thái Kolibri
- Độ dài dự án:
- Lâu dài (5 tháng)
Mô tả dự án
Bản tóm tắt
Tài liệu này trình bày chi tiết việc triển khai Nguyên tắc về kiểu và quản lý quy trình làm việc cho thông tin được ghi nhận của Learning Equality cho dự án Hệ sinh thái Kolibri.
Tổng quan
Đề xuất của tôi bao gồm 4 giai đoạn. Trong giai đoạn đầu tiên, tôi sẽ hoàn tất Hướng dẫn về phong cách tài liệu LE bằng các nguyên tắc hỗ trợ tiếp cận, viết và đề xuất định dạng theo các khái niệm và nguyên tắc về phong cách LE trong quá trình phát triển phần mềm. Trong giai đoạn thứ hai, tôi sẽ thực hiện quy trình Kiểm tra chất lượng đối với các tài liệu trên ReadTheDocs và GoogleDocs. Kế hoạch kiểm tra tích hợp việc sử dụng danh sách kiểm tra để đánh giá mức độ tuân thủ Nguyên tắc về kiểu. Những danh sách kiểm tra này sẽ giúp ghi lại các phát hiện và áp dụng các thay đổi đối với tài liệu. Trong giai đoạn thứ ba, tôi sẽ xử lý cấu trúc, giao diện và cảm nhận của các mẫu từ tài liệu ReadTheDocs và GoogleDocs. Tôi sẽ tạo một kho lưu trữ mẫu và hình ảnh trong Google Drive để xác định từng danh mục mẫu của các loại tài liệu chính để sử dụng lại trong các lần triển khai sắp tới. Tôi sẽ bổ sung nhiệm vụ này bằng cách tạo các mẫu để gửi vấn đề về tài liệu nhằm dễ dàng xác định trong quy trình xem xét yêu cầu kéo. Cuối cùng, tôi sẽ tạo một Hướng dẫn dành cho cộng tác viên để nhóm các tài nguyên hữu ích cho từng nhóm cộng tác viên nhằm nâng cao trải nghiệm truy cập thông tin của họ.
Mục đích và phạm vi
Mục đích của kế hoạch triển khai này là cải thiện trải nghiệm của những người dùng cuối khi sử dụng tài liệu của Kolibri, đồng thời giúp các thành viên trong nhóm và người đóng góp soạn thảo tài liệu hiệu quả hơn và tích cực cộng tác trong cộng đồng. Cách triển khai này áp dụng cho ReadTheDocs và tập hợp con tài liệu của Google Tài liệu trong Hệ sinh thái Kolibri.
Đối tượng
Đối tượng chính là những người triển khai, quản trị viên và người dùng cuối là những người sử dụng quan trọng nhất tài liệu Kolibri. Đối tượng phụ là các thành viên trong nhóm và cộng tác viên để sản xuất và sử dụng tài liệu Kolibri.
Mục tiêu
Hướng dẫn về quy tắc và hệ thống quy trình làm việc cho Tài liệu về hệ sinh thái Kolibri yêu cầu người dùng: Xây dựng tài liệu dễ hiểu bằng ngôn ngữ dễ tiếp cận và bố cục nhất quán. Duy trì việc duy trì các phương pháp đảm bảo chất lượng dựa trên tài liệu. Duy trì khả năng dễ dàng truy cập thông tin giữa các kênh tài liệu. Củng cố các sáng kiến cộng tác trong cộng đồng nguồn mở Kolibri.
Nguồn thông tin
Các nguồn thông tin của tôi là Kolibri, Kolibri Studio, tài liệu RTD về phát triển Kolibri và Bộ công cụ Kolibri trên Google Drive.
Radina Matic tuyệt vời đã giúp ích rất nhiều trong việc cung cấp các hoạt động khởi động và hoạt động dành riêng cho dự án. Ý kiến đóng góp của cô về những gì tổ chức này xem là ""Nguyên tắc"" và ""Hướng dẫn"" cũng như về sự tồn tại của Hướng dẫn dành cho cộng tác viên đã giúp tôi sắp xếp ý tưởng và soạn thảo kết luận.
Phần mềm
Tôi sẽ phát triển bản nháp Hướng dẫn quy tắc trong Google Tài liệu. Nền tảng tài liệu này rất phù hợp để lặp lại trong khi tài liệu đã sẵn sàng để xuất bản. Đối với quy trình Kiểm tra chất lượng, tôi sẽ sử dụng Google Biểu mẫu để tiến hành và đánh giá các tài liệu. Bảng tính sẽ lưu trữ các câu trả lời biểu mẫu để kiểm soát tài liệu. Tôi sẽ sử dụng GitHub để tái cấu trúc các tài liệu RTD. Tôi đã làm việc với Git, Gitkraken, GitHub và Gitlab. Tôi có kiến thức về Markdown và một số RestructuredText. Tôi dự định đóng góp vào việc sửa tài liệu để tiếp tục tìm hiểu cú pháp. Tôi sẽ dùng Sharex để tạo hình ảnh và ảnh GIF. Tôi thích công cụ này vì nó hiển thị ở nhiều định dạng đầu ra. Tôi sẽ sử dụng công cụ Biểu đồ để vẽ sơ đồ và chỉnh sửa hình ảnh. Phần mềm sơ đồ tích hợp hoàn hảo với GoogleDocs, Google Drive và LibreOffice. Trạng thái tài liệu Trong giai đoạn khám phá, tôi đã sửa đổi hầu hết tài liệu của Kolibri. Tôi nhận thấy có lỗi ngữ pháp, lỗi chính tả, không nhất quán về bố cục, kiểu chữ, cách sử dụng hình ảnh, cũng như lộ trình tài liệu gây nhầm lẫn trong hầu hết tài liệu của dự án. Ví dụ: Trong Hướng dẫn sử dụng của Kolibri, phần khắc phục sự cố là chủ đề phụ chứ không phải là chủ đề. Thông tin này rất quan trọng đối với người dùng cuối để họ có thể truy cập thông tin đó từ mục lục. Thay vào đó, họ có thể sử dụng thanh tìm kiếm và cây mục lục để mở rộng các chủ đề khác và tìm các bài viết khắc phục sự cố.
Để truy cập vào phần "Khắc phục sự cố", bạn phải tìm kiếm phần này hoặc mở rộng phần "Quản lý Kolibri" để nhận thấy rằng phần Khắc phục sự cố có trong tài liệu. Hướng dẫn và nguyên tắc Đối với đề xuất dự án này, tôi đã phân tích hai tài liệu: Hướng dẫn về cách trình bày tài liệu người dùng của LE Kolibri và Nguyên tắc dịch thuật ngữ thông thường. Trong Hướng dẫn về LE Kolibri, tôi đã đưa ra các đề xuất và nhận xét từ bản phác thảo chủ đề và kế hoạch Tài liệu đề xuất, cùng với một số điểm khác cần cải thiện trong Hướng dẫn. Đối với Nguyên tắc dịch thuật của LE, tôi đã thay đổi định dạng và kiểu dựa trên các đề xuất của mình và các quy ước hiện có trong Hướng dẫn về kiểu. Điều tôi chú ý nhất trong quá trình phân tích là sự hiểu lầm giữa các tài liệu được phân loại là Hướng dẫn và Nguyên tắc.
Kết quả
Ngoài các đề xuất và nhận xét, tôi đã kiểm tra chất lượng cho Hướng dẫn dịch LE bằng một biểu mẫu sơ bộ mà tôi sẽ giải thích chi tiết hơn trong nhiệm vụ Kiểm tra QA. Sau đây là một số nhận xét cuối cùng thu được từ quá trình đánh giá: Các đường liên kết bị hỏng trên trang web ICU Syntax .js Định dạng dùng để tạo các Nguyên tắc này không chính xác. Tài liệu này là Hướng dẫn chứ không phải Nguyên tắc. Kiểu chữ không nhất quán. Sử dụng tiêu đề và tiêu đề không đúng cách, Sử dụng ngôn từ không phù hợp và sử dụng từ rút gọn sai mục đích. Sử dụng văn bản thay thế không đúng cách. Quá nhiều câu lệnh/ lệnh lặp lại.
Kết quả của cả hai tài liệu này đều là một phần của Sản phẩm của đề xuất này.
Việc cần làm theo dự án
- Đề xuất về Hướng dẫn về quy tắc trình bày tài liệu người dùng LE (nhận xét)
- Nguyên tắc dịch thuật ngữ năng lượng thấp với phong cách và định dạng mới.
- Phác thảo chủ đề
- Tiến trình dự án
- Việc cần làm trong tài liệu