Giai đoạn hiện tại:
Chương trình Phần Tài liệu năm 2019 đã kết thúc vào ngày 6 tháng 3 năm 2020. Hãy xem dòng thời gian.
Trang này chứa các nguyên tắc dành cho người viết kỹ thuật về cách tạo báo cáo dự án khi bạn đã hoàn thành công việc cho Mùa Tài liệu năm nay.
Đang gửi báo cáo dự án
Khi giai đoạn hoàn thiện dự án bắt đầu, bạn sẽ có thể gửi báo cáo dự án bằng cách hoàn tất một biểu mẫu có trong phần hoàn thiện dự án trong hướng dẫn dành cho người viết kỹ thuật.
Thông tin cần đưa vào báo cáo dự án
Phần này mô tả loại thông tin bạn có thể cung cấp trong báo cáo dự án. Biểu mẫu báo cáo dự án sẽ bao gồm các trường văn bản tự do cũng như câu hỏi trắc nghiệm.
Liên kết đến bài tập của bạn
Cung cấp một đường liên kết trỏ đến phần mô tả của công việc bạn đã thực hiện.
Đường liên kết này phải dẫn đến một tài liệu chứa nội dung mô tả ngắn về công việc đã thực hiện, tài liệu về việc dự án nguồn mở đã hợp nhất vào kho lưu trữ, nội dung tóm tắt về trạng thái hiện tại của dự án, danh sách thách thức và bài học.
Đường liên kết này sẽ xuất hiện trong kết quả của Phần Tài liệu được xuất bản trên trang web. Kết quả được xuất bản thể hiện công việc bạn đã hoàn thành trong chương trình. Kết quả được xuất bản cũng là một cách tuyệt vời để bạn tham khảo lại bài tập của mình trong sơ yếu lý lịch.
Bạn nên chia sẻ đường liên kết của mình với người cố vấn và yêu cầu đánh giá trước khi gửi báo cáo dự án.
Các yêu cầu đối với báo cáo dự án
Hãy xem xét các yêu cầu sau đây:
- Nội dung được liên kết phải giúp bạn dễ dàng xác định nội dung bạn đã hoàn thành trong Phần Tài liệu, tức là những thay đổi bạn đã thực hiện hoặc tài liệu mới bạn đã viết.
- Công việc phải ở vị trí ổn định. Bạn không thể thay đổi URL sau khi gửi.
Người khác có thể sử dụng nội dung tại (hoặc được tham chiếu từ) mục tiêu của đường liên kết để xây dựng dựa trên nội dung của bạn.
- Nếu công việc của bạn đã hoàn thành 100%, những người khác có thể sử dụng công việc đó.
- Nếu công việc của bạn chưa hoàn thành 100%, thì bạn nên biết rõ những việc cần làm.
Ví dụ hay về cách mô tả tác phẩm của bạn
Bạn không cần phải làm tất cả (hoặc bất kỳ) việc nào trong số này, nhưng có thể đáp ứng các yêu cầu bằng một số cách sau đây:
Tạo một bài đăng trên blog hoặc trang web hoặc thông tin chính công khai trên GitHub mô tả công việc bạn đã thực hiện và liên kết đến các cam kết bạn đã thực hiện và kho lưu trữ bạn đã làm việc. Nếu dự án vẫn còn một việc cần làm, hãy thêm nội dung mô tả về công việc đó. Bạn cũng có thể chia sẻ những mục nổi bật hoặc khó khăn.
Đây là lựa chọn tốt nhất vì bạn có thể dễ dàng đưa nhiều thông tin vào. Điều này rất hữu ích vì nó thể hiện rõ công việc bạn đã làm, đồng thời giúp người khác dễ dàng sử dụng và hiểu nội dung đóng góp của bạn.
Nếu sử dụng GitHub và tất cả công việc của bạn được thực hiện bằng một yêu cầu lấy dữ liệu duy nhất, thì bạn có thể sử dụng đường liên kết đó.
- Hãy đảm bảo rằng nội dung mô tả của yêu cầu lấy dữ liệu được chi tiết.
- Hãy đảm bảo phần mô tả ghi chú rõ ràng rằng tác phẩm này dành cho Phần Tài liệu.
- Nếu yêu cầu kéo cần thêm thao tác sau khi Phần Tài liệu đã hết, hãy đảm bảo Phần Tài liệu gần đây nhất có ghi chú về việc này.
- Phương thức cung cấp báo cáo dự án này có lợi ích là có nhật ký thay đổi, danh sách các thay đổi và nhận xét đánh giá ở cùng một nơi.
Nếu kho lưu trữ GitHub của bạn có mục đích duy nhất là Phần Tài liệu, hãy thêm tệp README chứa thông tin chi tiết về tác phẩm của bạn.
Tạo một thư mục công khai trong Google Drive và bao gồm tất cả các bản vá bạn đã tạo.
Tạo một bảng tính công khai bằng Google Trang tính rồi liệt kê tất cả các thay đổi của bạn.
Liên kết đến một vấn đề duy nhất trong công cụ theo dõi lỗi công khai, trong đó chứa các thông tin tham chiếu rõ ràng đến tác phẩm của bạn và bất kỳ vấn đề nào khác thích hợp. Vấn đề này sẽ theo dõi tất cả công việc bạn đã thực hiện. Hãy đảm bảo vấn đề này liệt kê tất cả các thay đổi hoặc bạn có thể dễ dàng tìm thấy các thay đổi theo cách khác.
Liên kết đến một điểm thống nhất hoặc khác biệt về ngữ cảnh của các thay đổi. Hãy nhớ thêm tiêu đề có tên dự án viết kỹ thuật của bạn và bạn là ai để tiêu đề đó hữu ích cho những người khác.
Những ví dụ không phù hợp về cách mô tả tác phẩm của bạn
Bạn không nên làm những việc sau:
- Liên kết đến một tệp tarball hoặc zip chứa toàn bộ mã nguồn của dự án hoặc thư mục đang làm việc của bạn.
- Liên kết đến đầu kho lưu trữ nguồn chính của dự án. Ví dụ: nếu bạn đang phát triển Cpython, đường liên kết này sẽ không hữu ích: https://github.com/python/cpython.
- Liên kết đến bản sao của kho lưu trữ nguồn của dự án. Điều này khiến bạn khó biết được nội dung thay đổi là gì vì công việc của bạn kết hợp với công việc của người khác.
- Liên kết đến phần mô tả dự án của bạn trên trang web Season of Tài liệu.
Dành cho người cố vấn
Vui lòng giúp người viết kỹ thuật của bạn tạo một báo cáo dự án phù hợp. Bạn cần thực hiện việc này trước khi đưa ra đánh giá của riêng mình về tác phẩm của tác giả kỹ thuật.
Kiểm tra những thông tin sau:
- Nội dung bạn gửi phải đáp ứng các yêu cầu nêu trên.
- Nội dung gửi phải bao gồm nội dung mô tả công việc đã thực hiện, các yêu cầu được đáp ứng và lý do cho bất kỳ quyết định cụ thể nào được đưa ra.
Ý tưởng về Phần Tài liệu không phải là người viết nội dung kỹ thuật phải đưa ra nhiều tài liệu. Điều quan trọng là công việc đó phải có khả năng hữu ích cho dự án nguồn mở lưu trữ.