Giai đoạn hiện tại:
Chương trình Phần Tài liệu năm 2021 đã kết thúc vào ngày 14 tháng 12 năm 2021. Hãy xem dòng thời gian.
Giới thiệu về Phần Tài liệu
Season of Tài liệu là một chương trình bền vững do Văn phòng chương trình nguồn mở của Google quản lý. Mục tiêu của Phần Tài liệu là:
- Hỗ trợ các dự án nguồn mở để giải quyết vấn đề của dự án thông qua tài liệu
- Tạo cơ hội cho các nhà văn kỹ thuật lấy kinh nghiệm trong lĩnh vực nguồn mở
- Nâng cao nhận thức về nguồn mở, tài liệu và nội dung kỹ thuật
- Thu thập và chia sẻ thông tin về các chỉ số hiệu quả trong tài liệu nguồn mở
Bạn có thể xem thêm thông tin về Phần Tài liệu trên trang web của chương trình này.
Tổng quan về chương trình năm 2021
Các thay đổi đối với chương trình năm 2021
Trong năm 2019 và 2020, các tổ chức và người viết kỹ thuật đã đăng ký riêng biệt cho chương trình Phần Tài liệu, còn người viết nội dung kỹ thuật được ghép nối với các tổ chức theo quản trị viên của chương trình Phần Tài liệu. Các tổ chức giới thiệu người cố vấn làm việc với các nhà văn kỹ thuật, những người đã nhận được tiền trợ cấp cho tác phẩm của họ theo địa điểm làm việc. Chương trình này đo lường xem người viết nội dung kỹ thuật, cố vấn và quản trị viên của tổ chức có hài lòng với việc tham gia chương trình hay không, nhưng không đo lường kết quả ghi nhận tài liệu.
Năm 2021, nhóm phụ trách Phần Tài liệu đã thực hiện những thay đổi quan trọng đối với chương trình này, chuyển trọng tâm sang việc đo lường kết quả của tài liệu và giúp các tổ chức cũng như người viết kỹ thuật linh hoạt hơn.
- Những tổ chức đã áp dụng đề xuất dự án, bao gồm cả ngân sách và các chỉ số được đề xuất
- Tác giả về kỹ thuật không còn đăng ký để được kết nối với các tổ chức thông qua Google nữa, mà đăng ký trực tiếp vào các tổ chức được chấp nhận
- Các tổ chức được chấp nhận đã nhận được các khoản tài trợ qua Open Collective, nơi họ dùng để trả tiền cho nhà văn kỹ thuật
- Tổ chức đã đặt mức thù lao cho người viết nội dung kỹ thuật
- Các tổ chức đã gửi đánh giá cuối cùng và nghiên cứu điển hình, đồng thời trả lời khảo sát tiếp theo
Phát hiện chung năm 2021
Tổ chức
- Những thay đổi trong chương trình năm 2021 khiến số tổ chức đăng ký giảm 30% (chúng tôi nhận thấy số tổ chức đăng ký trong năm 2021 ít hơn 30% so với năm 2020), nhưng quản trị viên của tổ chức năm 2021 hài lòng hơn một chút với chương trình so với quản trị viên năm 2020 (93% so với 91%)
Vấn đề, loại tài liệu và chỉ số
- Hầu hết dự án đều tập trung vào việc soạn thảo tài liệu để giảm gánh nặng của người bảo trì (thông qua việc giảm các vấn đề/câu hỏi) và/hoặc tăng mức độ tham gia dự án (của người dùng dự án hoặc người đóng góp).
- 50% trong số các tổ chức được chấp nhận đã tạo nội dung Hướng dẫn hoặc Hướng dẫn.
- Hơn 50% tổ chức được chấp nhận cho rằng tài liệu hiện tại của họ bị thiếu, vô tổ chức hoặc đã lỗi thời.
- Các dự án thường muốn đo lường hiệu quả của tài liệu thông qua hoạt động tương tác, đặc biệt là số lượng vấn đề phát sinh ít hơn và nhiều khách truy cập hơn vào tài liệu cũng như mức độ tham gia vào các dự án.
- Tính đến tháng 11 năm 2022, có 25/30 dự án đang được phản hồi:
- 18 dự án cho biết họ đã đáp ứng các chỉ số ban đầu
- 5 dự án đã đáp ứng các chỉ số đã sửa đổi
- 2 dự án cho biết vẫn còn quá sớm để thông báo
Tham gia chương trình
- Tuyển dụng, tuyển dụng và trả tiền cho cây bút kỹ thuật là phần khó khăn nhất trong chương trình đối với các quản trị viên tổ chức.
- Tính đến tháng 11 năm 2022, có 24/30 tổ chức phản hồi:
- 18 tổ chức vẫn đang hỗ trợ người viết nội dung kỹ thuật trong phần Tài liệu của họ (với tư cách là người đóng góp liên tục hoặc người trả lời câu hỏi)
- 4 tổ chức đang hợp tác với người viết nội dung kỹ thuật trong phần Tài liệu của họ trong vai trò được trả phí
- 18 tổ chức vẫn đang hỗ trợ người viết nội dung kỹ thuật trong phần Tài liệu của họ (với tư cách là người đóng góp liên tục hoặc người trả lời câu hỏi)
Thông tin nổi bật trong năm 2021
- Nhiều dự án cho thấy người viết kỹ thuật có ý định tiếp tục làm việc với dự án của họ sau khi chương trình Phần tài liệu kết thúc
- Metanorma có rất nhiều người viết đơn đăng ký tham gia chương trình kỹ thuật đến mức họ tìm được khoản tiền phù hợp để thuê thêm một nhà biên kịch làm việc cùng với tác giả tham gia chương trình Season of Tài liệu được hỗ trợ trong chương trình
- Moja Global nhận thấy rằng cộng đồng rất tích cực tham gia vào tài liệu và thành lập một Nhóm làm việc về tài liệu mới để tạo điều kiện cho nhiều cộng tác viên tham gia vào tài liệu của dự án
Dữ liệu tóm tắt năm 2021
Năm 2021, 82 tổ chức đã đăng ký và 30 tổ chức nguồn mở đã được chấp nhận tham gia chương trình. (Xem Hướng dẫn tạo ứng dụng của bạn để biết các tiêu chí lựa chọn.) Bạn có thể xem danh sách đầy đủ các tổ chức tham gia trên trang web Phần Tài liệu. Tất cả 30 tổ chức được chấp nhận đã gửi báo cáo nghiên cứu điển hình cuối cùng để hoàn tất quá trình tham gia chương trình năm 2021.
Giới thiệu về tổ chức
Các tổ chức tham gia Season of Tài liệu 2021 đại diện cho nhiều dự án nguồn mở đa dạng. Nhóm thuần tập năm 2021 bao gồm:
- Các dự án ngôn ngữ lớn như Julia, Perl và R
- Dự án về giáo dục, khí hậu, công nghệ tài chính, y tế, dịch vụ thư viện, học máy, phổ khối, hợp đồng công và robot
- Các dự án tập trung vào nhà phát triển, bao gồm cả công cụ kỹ thuật hỗn hợp, công cụ kiểm thử mờ, SDK bot trò chuyện, quy trình phân tích cấu trúc phần mềm, công cụ theo dõi hiệu suất và công cụ lập trình trực quan
- Các dự án tài liệu dành cho công cụ tài liệu, chẳng hạn như Làm lạicly và Metanorma
Các dự án trong hệ sinh thái Python là danh mục con lớn nhất. Nhóm thuần tập năm 2021 bao gồm ArviZ, NumPy, MicroPython, PyMC3, PyTorch-Ignite và SymPy.
Chúng tôi không thu thập bất kỳ siêu dữ liệu nào về các dự án (chẳng hạn như ngày thành lập, sự phân bổ theo khu vực địa lý của người đóng góp, số lượng người đóng góp hoặc quy mô cơ sở người dùng).
Chúng tôi đã yêu cầu các dự án cho biết họ sử dụng giấy phép nguồn mở nào.
Các vấn đề về tài liệu mà các tổ chức đã nêu ra trong năm 2021 là những vấn đề rất phổ biến trong cả dự án nguồn mở và tài liệu kỹ thuật nói chung.
Những vấn đề hàng đầu mà các tổ chức hy vọng giải quyết được trong chương trình năm 2021 bao gồm:
Xin lưu ý rằng các tổ chức có thể báo cáo nhiều vấn đề về tài liệu. Để biết thêm thông tin cụ thể, hãy xem trang kết quả của Mùa Tài liệu 2021. Trang này liên kết đến các nghiên cứu điển hình đầy đủ về từng tổ chức.
Các loại tài liệu được tạo
Hướng dẫn là loại tài liệu được đề cập nhiều nhất trong các nghiên cứu điển hình năm 2021.
Các loại tài liệu khác được đề cập trong nghiên cứu điển hình bao gồm Quy trình tạo tài liệu dưới dạng mã, Sơ đồ, Bảng thuật ngữ, Hướng dẫn về văn phong, Câu hỏi thường gặp, Quốc tế hoá, Lớp học lập trình, Mô hình nội dung, Mô-đun, Tài liệu về khái niệm, Thông báo lỗi, Nghiên cứu về người dùng, Readme, Cơ sở kiến thức.
Một số danh mục trong số này không rõ ràng và một dự án tài liệu có thể chứa nhiều loại hoặc tính năng tài liệu.
Một số dự án đã được tham chiếu cụ thể bằng cách sử dụng khung DiátTrục làm hướng dẫn lập kế hoạch các loại tài liệu tương ứng.
Để biết thêm thông tin cụ thể, hãy xem trang kết quả của Mùa Tài liệu 2021. Trang này liên kết đến các nghiên cứu điển hình đầy đủ về từng tổ chức.
Ngân sách
Năm 2021, yêu cầu ngân sách trung bình là 10.200 đô la và mức trung bình là 10.000 đô la. Chỉ có ba tổ chức yêu cầu và nhận được khoản tài trợ tối đa có thể (15.000 đô la) và ba tổ chức khác yêu cầu khoản tài trợ thấp nhất có thể (5.000 đô la).
Chỉ số
Những dự án được nêu trong ví dụ điển hình sẽ nghiên cứu các chỉ số mà họ dùng để đánh giá mức độ thành công của các dự án tài liệu.
Các chỉ số được đề xuất hàng đầu là:
Các chỉ số được đề xuất khác bao gồm Số sao trên GitHub, Thời gian trên trang, Số lượt chuyển đổi trên danh sách gửi thư, Thử nghiệm chất lượng của người dùng, Số người tham gia diễn đàn, Số đối tác/tình nguyện viên/hoạt động tích hợp.
Do khoảng thời gian từ khi hoàn thành dự án viết nội dung kỹ thuật cho đến khi gửi nghiên cứu điển hình là khoảng thời gian ngắn, nên hầu hết nhóm thuần tập năm 2021 đã không thể thu thập đủ dữ liệu để xác định liệu họ đã đáp ứng các chỉ số ban đầu hay chưa.
Để biết thêm thông tin cụ thể, hãy xem trang kết quả của Mùa Tài liệu 2021. Trang này liên kết đến các nghiên cứu điển hình đầy đủ về từng tổ chức.
Làm việc với các nhà văn kỹ thuật
Thay đổi lớn nhất đối với chương trình Season of Tài liệu năm 2021 liên quan đến cách các dự án hợp tác với các nhà biên kịch kỹ thuật. Trong những mùa giải trước, nhà văn kỹ thuật nộp đơn trực tiếp cho Google và được quản trị viên chương trình ghép cặp với các dự án và được Google trả tiền lương cố định.
Năm 2021, những người viết kỹ thuật trực tiếp đăng ký tham gia các dự án và dự án sẽ thiết lập ngân sách thù lao cho biên tập viên kỹ thuật, cùng các khoản thanh toán được thực hiện qua Quỹ Open Collective của Season of Tài liệu.
Hầu hết các dự án tham gia chương trình năm 2021 đều có ít hoặc không có kinh nghiệm trong việc tuyển dụng hoặc tuyển dụng nhà biên kịch kỹ thuật. Nhiều dự án cho biết phần này trong quy trình là một phần cần được hỗ trợ thêm. Để đáp lại ý kiến phản hồi này, nhóm phụ trách Phần Tài liệu đã bổ sung tài liệu về cách tạo thoả thuận với tác giả về kỹ thuật vào hướng dẫn chương trình.
Đề xuất tuyển dụng
Chúng tôi yêu cầu các dự án đưa ra đề xuất cho những dự án khác có quan tâm đến việc tham gia Phần Tài liệu. Các đề xuất tuyển dụng hàng đầu bao gồm:
- Chia sẻ tài liệu tuyển dụng cho người viết nội dung kỹ thuật càng sớm càng tốt, thậm chí là trước khi bạn được chấp nhận tham gia chương trình. Đề nghị cộng đồng của bạn giới thiệu các ứng viên tiềm năng.
- Chia sẻ rộng rãi ra bên ngoài các kênh dự án. Sử dụng ngôn từ không phân biệt đối xử và trực tiếp khuyến khích các ứng viên có xuất thân ít phổ biến để đăng ký tham gia.
- Nắm được những công cụ cần thiết cho quá trình sáng tạo tài liệu và tuyển dụng những người viết nội dung kỹ thuật có kinh nghiệm sử dụng các công cụ đó.
- Tạo kỳ vọng rõ ràng cho người viết nội dung kỹ thuật về các sản phẩm và mốc quan trọng, kênh truyền thông và yêu cầu đăng ký, quy trình và thời gian thanh toán.
- Cân nhắc đầu tư vào các thành viên trong cộng đồng và giúp họ phát triển với vai trò là người viết nội dung kỹ thuật bằng cách sử dụng tác giả kỹ thuật của Season of Tài liệu để hướng dẫn và huấn luyện.
- Dành nhiều thời gian hơn dự kiến cho việc giới thiệu tác giả kỹ thuật, trả lời câu hỏi và hỗ trợ trong suốt chương trình, đặc biệt nếu người viết nội dung kỹ thuật không có kinh nghiệm trước đó trong lĩnh vực dự án của bạn.
- Ghi lại quy trình tuyển dụng, tuyển dụng và hướng dẫn ban đầu để sử dụng cho các dự án trong tương lai.
(Lưu ý: không phải dự án nào đã được nêu trong nghiên cứu điển hình mà trong đó họ tuyển các ứng cử viên viết kỹ thuật.)
Vấn đề thường gặp khi làm việc với người viết nội dung kỹ thuật
Những người viết nội dung kỹ thuật tham gia một số dự án đã phải ngừng việc do COVID hoặc các bệnh lý khác, hoặc vì trách nhiệm liên quan đến đại dịch của gia đình. Một số dự án báo cáo các vấn đề liên quan đến thông tin liên lạc liên quan đến việc không khớp múi giờ hoặc vấn đề về kết nối Internet.
Các dự án nhận thấy họ đã đánh giá thấp những khó khăn liên quan đến việc tham gia cộng đồng hoặc thiết lập chuỗi công cụ tài liệu của dự án.
Một số dự án chậm thanh toán cho tác giả kỹ thuật do các vấn đề về ngân hàng với Open Collective hoặc do quốc gia của tác giả có quy định hạn chế về việc thanh toán.
Tài liệu của chương trình về phí của Open Collective không rõ ràng: Google đã chi trả các khoản phí giao dịch của Open Collective cho việc chuyển tiền ban đầu tới dự án, chứ không phải phí giao dịch do một số kênh thanh toán khác áp đặt (chẳng hạn như phí chuyển đổi tiền tệ). Chúng tôi sẽ làm việc để làm rõ hơn điều này trong tài liệu dành cho các chương trình sau này.
Khảo sát tiếp theo
Trong chương trình Phần Tài liệu, các dự án được mời tham gia các cuộc khảo sát tiếp theo. Chúng tôi đã gửi 3 bản khảo sát vào tháng 5, tháng 8 và tháng 11 năm 2022.
Khảo sát tiếp theo yêu cầu các dự án xác nhận rằng các đường liên kết đến đề xuất và nghiên cứu điển hình của họ vẫn hoạt động. Khảo sát này cũng bao gồm các câu hỏi về mức độ thành công của các dự án của họ (được xác định bằng các chỉ số mà họ đặt ra trong nghiên cứu điển hình) và việc tiếp tục tham gia cũng như trả thù lao cho những người viết bài kỹ thuật của dự án:
- Bạn vẫn đang cộng tác với người viết nội dung kỹ thuật cho phần Phần Tài liệu chứ?
- Nếu người viết nội dung kỹ thuật vẫn đang làm việc với dự án của bạn, thì họ có được trả thù lao theo hình thức nào không?
- Tại thời điểm này, bạn có thấy dự án lập tài liệu của mình đã thành công không?
Câu hỏi trong tương lai
Như thường lệ, chúng ta càng tìm hiểu nhiều về tài liệu trong nguồn mở, chúng ta càng muốn tìm hiểu nhiều hơn! Trong các mùa giải sau này, chúng tôi hy vọng có thể tìm hiểu được:
- Liệu các miền dự án có tương quan với lựa chọn loại tài liệu hoặc lựa chọn chỉ số hay không
- Các phương pháp tuyển dụng và phương pháp giới thiệu viết nội dung kỹ thuật nào hiệu quả nhất trong việc hoàn thành dự án và giữ chân người viết nội dung kỹ thuật
- Tiến trình hợp lý để đo lường hiệu quả của tài liệu
Mặc dù có nhiều câu hỏi chúng tôi muốn điều tra, nhưng chúng tôi cũng muốn tôn trọng thời gian của các quản trị viên và nhà bảo trì dự án nguồn mở tham gia vào Phần Tài liệu. Ưu tiên hàng đầu của chương trình này là hỗ trợ các dự án giải quyết vấn đề thông qua tài liệu.