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ở:
- ScummVM
- Người viết nội dung kỹ thuật:
- b-gent
- Tên dự án:
- Cải thiện tài liệu về mã nguồn thông qua Doxygen
- Thời lượng dự án:
- Thời gian tiêu chuẩn (3 tháng)
Mô tả dự án
Tài liệu về API ScummVM (mã nguồn) hiện tại được xuất bản tại đây: https://doxygen.scummvm.org/modules.html
Thật không may, điều này còn thiếu ở nhiều lĩnh vực:
1) Thực tế không có cấu trúc nào cho nó, mọi thông tin đều trôi nổi trên cùng một cấp độ.
2) Các phần tử C++ được ghi lại không nhất quán với một số phần tử hoàn toàn không được ghi lại. Đây là vấn đề mà tổ chức đề cập đến là một trong những vấn đề chính.
3) Nội dung lỗi thời và không được dùng nữa vẫn hiển thị trong kết quả.
4) Ngôn ngữ và việc sử dụng tính năng gắn thẻ doxygen phải được thực hiện nhất quán hơn. Cần có một bộ quy tắc cho việc này. Đây có thể là cơ sở cho định dạng tài liệu trong tương lai cho dự án này.
5) Có thể cải thiện CSS doxygen được sử dụng trên trang này để nó giống với trang web ScummVM: https://www.scummvm.org
Bạn có thể giải quyết tất cả các vấn đề này trong dự án Phần Tài liệu.
Ứng dụng Phần Tài liệu này đi kèm với một bản nháp mà tôi đã mở trong dự án để minh hoạ một số điểm cải tiến tiềm năng mà tôi đề xuất: https://github.com/scummvm/scummvm/pull/2361 Xem phần mô tả để biết một số thông tin chi tiết về nội dung của ứng dụng và xem điểm khác biệt.
Cụ thể, công tác PR liên quan đến những vấn đề sau:
1) Tôi nghĩ điều khó hiểu nhất hiện tại đối với các cộng tác viên tiềm năng mới và nói chung là bất kỳ ai xem tài liệu API hiện tại là sự thiếu cấu trúc. Việc ra mắt tài liệu về API có cấu trúc sẽ giúp cải thiện khả năng đọc, dễ tìm và do đó giúp cải thiện khả năng hữu dụng của tài liệu. Đó là lý do tại sao PR của tôi giới thiệu nhóm doxygen cho tất cả các tệp tiêu đề trong thư mục "common". Với cấu trúc mới này, nếu ai đó muốn tìm tài liệu về API liên quan đến hệ điều hành (ví dụ), họ có thể dễ dàng tìm thấy trong phần điều hướng.
2) Tệp cấu hình doxygen mới được thiết lập để cho phép tạo tài liệu này.
3) Tệp "links.doxyfile" mà từ đó tất cả các đường liên kết được sử dụng trong tài liệu đều có thể là một nguồn duy nhất. Một cơ chế hữu ích khi làm việc với doxygen.
4) Một CSS doxygen đã sửa đổi. Thông tin này hiện được lấy từ một dự án nguồn mở khác và chỉ là điểm khởi đầu. Tốt nhất là giao diện của trang doxygen nhất quán hơn hoặc ít hơn với trang web ScummVM.
Điều mà PR không đề cập đến nhưng chắc chắn cần được xử lý chính nội dung đó. Ý tôi là xác định các phần thiết yếu của mã không được ghi lại, những phần không được ghi lại đầy đủ hoặc các phần mã lỗi thời cần được xoá khỏi tài liệu. Do tôi chưa từng tham gia dự án này nên cần có sự hướng dẫn của người cố vấn để đạt được mục tiêu này.
Tất nhiên, việc có triển khai bất cứ điều gì từ bộ phận PR hay không còn tuỳ thuộc vào việc chúng ta thảo luận với tổ chức. Ý tưởng của tôi là hành động nói to hơn lời nói, vì vậy tôi quyết định thể hiện những gì mình có thể làm thay vì chỉ mô tả điều đó trong ứng dụng.
Tổ chức đưa ra tiến trình sơ bộ sau đây (1 Tuần/Tuần) (Tuần 1 – Tuần 1) Việc cần làm chính trong tuần Tuần 1 và Tuần 1
Thay đổi duy nhất mà tôi đề xuất là hãy bắt đầu bằng việc xây dựng cấu trúc, như đã đề cập. Điều này có thể được thực hiện trong tuần 1 và 2, cùng với việc thiết lập bản dựng doxygen (phần lớn đã được thực hiện) và làm mới da Doxygen. Sau đó, tôi đồng ý rằng việc xem xét từng khía cạnh một với người cố vấn để xác định các vấn đề và cải thiện tài liệu về doxygen sẽ hợp lý nhất.
Tôi thấy đây là dự án có độ dài tiêu chuẩn nhưng tôi chắc chắn rằng có các điểm cải tiến khác liên quan đến tài liệu API có thể thực hiện được sau khi dự án GSoD kết thúc. Ví dụ: nghĩ ra một hướng dẫn định kiểu tài liệu và thêm vào wiki để những người đóng góp biết cách ghi lại mã mà họ đang thêm.
Tôi rất sẵn lòng trợ giúp những công việc tương tự sau khi GSoD kết thúc. Tôi chắc chắn ScummVM có thể sử dụng một người viết kỹ thuật để đảm bảo rằng tài liệu API của họ có chất lượng tốt và khả năng hữu dụng. Tôi cũng có thể thấy rằng có các dự án tài liệu khác mà tôi có thể giúp bạn trong tương lai, chẳng hạn như tạo hướng dẫn về cách sử dụng trình bổ trợ.