Giới thiệu về Season of Docs
Season of Docs 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 Season of Docs là:
- Cung cấp tài liệu hỗ trợ để giải quyết các vấn đề về dự án nguồn mở
- Cho phép người viết nội dung kỹ thuật có cơ hội tích luỹ kinh nghiệm về nguồn mở
- Nâng cao nhận thức về nguồn mở, tài liệu và văn bản 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ề Chương trình mùa tài liệu trên trang web của chương trình.
Tổng quan về chương trình năm 2021
Những thay đổi về chương trình năm 2021
Trong năm 2019 và 2020, các tổ chức và nhà văn kỹ thuật đã đăng ký riêng cho chương trình Season of Docs. Sau đó, quản trị viên của chương trình Season of Docs sẽ so khớp nhà văn kỹ thuật với các tổ chức. Các tổ chức đã cung cấp người cố vấn để làm việc với các nhà văn kỹ thuật. Họ nhận được một khoản tiền trợ cấp cho công việc của mình dựa trên vị trí của họ. Chương trình này đo lường xem các nhà văn kỹ thuật, người cố vấn và quản trị viên 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ả của tài liệu.
Năm 2021, nhóm Season of Docs đã thực hiện những thay đổi đáng kể đối với chương trình, chuyển trọng tâm sang việc đo lường kết quả của tài liệu và cho phép các tổ chức và người viết kỹ thuật linh hoạt hơn.
- Các tổ chức đã gửi đề xuất dự án, bao gồm cả ngân sách và các chỉ số được đề xuất
- Người viết nội dung kỹ thuật không còn đăng ký thông qua Google để được so khớp với các tổ chức nữa mà đăng ký trực tiếp với các tổ chức được chấp nhận
- Các tổ chức được chấp nhận đã nhận được khoản tài trợ thông qua Open Collective để trả lương cho các nhà văn kỹ thuật
- Các 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 bản đánh giá cuối cùng và nghiên cứu điển hình, đồng thời trả lời các cuộc khảo sát tiếp theo
Kết quả chung năm 2021
Tổ chức
- Những thay đổi trong chương trình năm 2021 đã khiến ít tổ chức đăng ký hơn (chúng tôi nhận thấy số lượng tổ chức đăng ký năm 2021 giảm 30% so với năm 2020), nhưng các quản trị viên tổ chức năm 2021 lại hài lòng hơn một chút với chương trình so với các 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 các dự án đều tập trung vào việc tạo tài liệu để giảm gánh nặng cho người bảo trì (thông qua việc giảm 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% số tổ chức được chấp nhận đã tạo nội dung Hướng dẫn hoặc Cách làm.
- Hơn 50% số tổ chức được chấp nhận cho rằng tài liệu hiện tại của họ còn thiếu, không được sắp xếp hợp lý 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 các lượt tương tác, đặc biệt là ít vấn đề được nêu ra hơn và có nhiều khách truy cập vào tài liệu cũng như tham gia vào dự án hơn.
- Kể từ tháng 11 năm 2022, 25 trong số 30 dự án đã trả lời:
- 18 dự án cho biết họ đã đạt được 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 để biết
Tham gia chương trình
- Việc tuyển dụng, thuê và trả lương cho người viết nội dung kỹ thuật là phần khó khăn nhất của chương trình đối với quản trị viên tổ chức.
- Tính đến tháng 11 năm 2022, 24 trong số 30 tổ chức đã trả lời:
- 18 tổ chức vẫn đang làm việc với các nhà văn kỹ thuật của họ trong chương trình Mùa Tài liệu (với vai trò là người đóng góp liên tục hoặc là nguồn lực để trả lời câu hỏi)
- 4 tổ chức đang làm việc với các nhà văn kỹ thuật của họ trong chương trình Season of Docs với vai trò được trả phí
- 18 tổ chức vẫn đang làm việc với các nhà văn kỹ thuật của họ trong chương trình Mùa Tài liệu (với vai trò là người đóng góp liên tục hoặc là nguồn lực để trả lời câu hỏi)
Điểm nổi bật năm 2021
- Nhiều dự án cho biết rằng người viết kỹ thuật của họ dự định tiếp tục làm việc với dự án của họ sau khi chương trình Mùa tài liệu kết thúc
- Metanorma đã nhận được rất nhiều đơn đăng ký của các nhà văn kỹ thuật đủ tiêu chuẩn, nên họ đã tìm được nguồn tài trợ phù hợp để thuê thêm một nhà văn làm việc cùng với nhà văn được hỗ trợ trong Chương trình viết tài liệu
- Moja Global nhận thấy cộng đồng rất quan tâm đến tài liệu nên đã thành lập một Nhóm làm việc về tài liệu mới để cho phép nhiều cộng tác viên hơn tham gia vào việc lập tài liệu 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 để biết 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 của chương trình Season of Docs. Tất cả 30 tổ chức được chấp nhận đều đã 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 Chương trình viết tài liệu 2021 đại diện cho nhiều dự án nguồn mở. 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
- Các dự án về giáo dục, khí hậu, công nghệ tài chính, chăm sóc sức khoẻ, dịch vụ thư viện, học máy, quang phổ khối, hợp đồng công khai và robot
- Các dự án tập trung vào nhà phát triển, bao gồm các công cụ kỹ thuật hỗn loạn, công cụ tìm lỗi mã nguồn, SDK chatbot, quy trình phân tích thành phần phần mềm, công cụ giám sát hiệu suất và công cụ lập trình trực quan
- Dự án tài liệu cho các công cụ tài liệu, chẳng hạn như Redocly và Metanorma
Các dự án hệ sinh thái Python là danh mục phụ lớn nhất. Nhóm 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, vị trí đị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 giấy phép nguồn mở mà họ sử dụng.
Các vấn đề về tài liệu mà các tổ chức năm 2021 nêu ra 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.
Sau đây là một số vấn đề hàng đầu mà các tổ chức muốn giải quyết trong chương trình năm 2021:
Xin lưu ý rằng 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 chi tiết, hãy xem trang kết quả của Chương trình tài liệu 2021. Trang này có đường liên kết đến các nghiên cứu điển hình đầy đủ cho 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 đến 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 các nghiên cứu điển hình bao gồm Quy trình tài liệu dưới dạng mã, Sơ đồ, Từ điển, Hướng dẫn về kiểu, Câu hỏi thường gặp, Bản địa hoá, Lớp học lập trình, Mô hình nội dung, Mô-đun, Tài liệu khái niệm, Thông báo lỗi, Nghiên cứu người dùng, Readme, Cơ sở kiến thức.
Một số danh mục 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átaxis làm hướng dẫn để lập kế hoạch cho các loại tài liệu của dự án.
Để biết thêm thông tin chi tiết, hãy xem trang kết quả của Chương trình tài liệu 2021. Trang này có đường liên kết đến các nghiên cứu điển hình đầy đủ cho từng tổ chức.
Ngân sách
Trong năm 2021, yêu cầu ngân sách trung bình là 10.200 đô la và giá trị trung bình là 10.000 đô la. Chỉ có 3 tổ chức yêu cầu và nhận được khoản tài trợ tối đa có thể (15.000 USD) và 3 tổ chức khác yêu cầu khoản tài trợ thấp nhất có thể (5.000 USD).
Chỉ số
Các dự án được nêu trong nghiên cứu điển hình của họ là những chỉ số mà họ đang sử dụng để đánh giá mức độ thành công của dự án tài liệu.
Các chỉ số được đề xuất hàng đầu là:
Các chỉ số đề xuất khác bao gồm Số sao trên GitHub, Thời gian trên trang, Lượt chuyển đổi danh sách gửi thư, Thử nghiệm định tính người dùng, Số người tham gia diễn đàn, Số đối tác/người tình nguyện/nền tảng tích hợp.
Do khoảng thời gian ngắn giữa thời điểm hoàn thành dự án viết kỹ thuật và thời điểm gửi nghiên cứu điển hình, 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 xem họ đã đạt được các chỉ số ban đầu hay chưa.
Để biết thêm thông tin chi tiết, hãy xem trang kết quả của Chương trình tài liệu 2021. Trang này có đường liên kết đến các nghiên cứu điển hình đầy đủ cho 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 Docs năm 2021 liên quan đến cách các dự án làm việc với các nhà văn kỹ thuật. Trong các mùa trước, các nhà văn kỹ thuật đã trực tiếp đăng ký với Google và được quản trị viên chương trình so khớp với các dự án, đồng thời được Google trực tiếp trả một khoản tiền trợ cấp cố định.
Năm 2021, các nhà văn kỹ thuật đã trực tiếp đăng ký tham gia các dự án và các dự án này đã đặt ngân sách cho việc trả thù lao cho nhà văn kỹ thuật. Khoản thanh toán được thực hiện thông qua Quỹ Open Collective của Chương trình Season of Docs.
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 tuyển dụng hoặc thuê người viết nội dung kỹ thuật. Nhiều dự án cho biết đây là một phần của quy trình cần được hỗ trợ nhiều hơn. Để phản hồi ý kiến này, nhóm Season of Docs đã thêm tài liệu về cách tạo thoả thuận với người viết nội dung kỹ thuật vào hướng dẫn chương trình.
Đề xuất về việc tuyển dụng
Các dự án được yêu cầu đề xuất những dự án khác muốn tham gia Chương trình viết tài liệu. Sau đây là những đề xuất hàng đầu về việc tuyển dụng:
- Chia sẻ tài liệu tuyển dụng cho các nhà văn kỹ thuật càng sớm càng tốt, ngay cả trước khi bạn được chấp nhận tham gia chương trình. Yêu cầu cộng đồng đề cử những người có thể tham gia.
- 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 những ứng viên thuộc những nhóm ít được quan tâm đăng ký.
- Tìm hiểu những công cụ cần thiết cho quy trình tạo tài liệu và tuyển dụng các nhà văn kỹ thuật có kinh nghiệm sử dụng các công cụ đó.
- Đặt ra rõ ràng kỳ vọ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 liên lạc và thời điểm báo cáo, cũng như quy trình và thời gian thanh toán.
- Hãy cân nhắc việ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 tư cách là nhà văn kỹ thuật bằng cách sử dụng nhà văn kỹ thuật của Chương trình viết tài liệu để hướng dẫn và đào tạo.
- Hãy dành nhiều thời gian hơn dự kiến để hướng dẫn cho người viết nội dung kỹ thuật, trả lời câu hỏi và hỗ trợ trong suốt chương trình, đặc biệt là nếu người viết nội dung kỹ thuật chưa có kinh nghiệm trong lĩnh vực của dự án.
- Ghi lại quy trình tuyển dụng, thuê và giới thiệu nhân viên để sử dụng cho các dự án trong tương lai.
(Lưu ý: không phải dự án nào cũng được nêu trong nghiên cứu điển hình về việc họ tuyển dụng ứng viên viết nội dung kỹ thuật.)
Các vấn đề thường gặp khi làm việc với người viết nội dung kỹ thuật
Một số dự án đã phải bỏ dở do tác động của COVID hoặc các bệnh khác, hoặc do trách nhiệm gia đình liên quan đến đại dịch. Một số dự án đã báo cáo vấn đề về việc liên lạc liên quan đến sự không khớp múi giờ hoặc vấn đề kết nối Internet.
Các dự án nhận thấy rằng họ đã đánh giá thấp những khó khăn liên quan đến việc làm quen với 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 bị chậm trễ trong việc thanh toán cho các nhà văn kỹ thuật do các vấn đề về ngân hàng với Open Collective hoặc do quốc gia cư trú của các nhà văn có các quy định hạn chế về việc thanh toán.
Tài liệu chương trình về phí của Open Collective không rõ ràng: Google đã chi trả phí giao dịch của Open Collective cho lần chuyển tiền ban đầu đến các dự án, nhưng không chi trả phí giao dịch do một số kênh thanh toán khác áp dụng (chẳng hạn như phí chuyển đổi tiền tệ). Chúng tôi sẽ cố gắng trình bày rõ ràng hơn về vấn đề này trong tài liệu cho các chương trình trong tương lai.
Bài khảo sát tiếp theo
Trong chương trình Season of Docs, các dự án được yêu cầu 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.
Bản khảo sát tiếp theo yêu cầu các dự án xác nhận rằng đườ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. Bản khảo sát cũng bao gồm các câu hỏi về mức độ thành công của dự án (do các chỉ số mà họ đặt trong nghiên cứu điển hình xác định) cũng như việc tiếp tục tham gia và nhận thù lao của các nhà văn kỹ thuật dự án:
- Bạn vẫn đang làm việc với nhà văn kỹ thuật của mình trong chương trình Season of Docs không?
- 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, họ có được đền bù theo cách nào không?
- Tại thời điểm này, bạn có cảm thấy dự án tài liệu của mình đã thành công không?
Câu hỏi trong tương lai
Như mọi khi, chúng ta càng tìm hiểu nhiều về tài liệu trong nguồn mở, thì chúng ta càng muốn tìm hiểu nhiều hơn! Trong các mùa sau, chúng tôi hy vọng sẽ tìm hiểu được:
- Liệu miền của dự án có tương quan với lựa chọn về loại tài liệu hoặc chỉ số hay không
- Những phương pháp tuyển dụng và hướng dẫn ban đầu nào hiệu quả nhất để 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 mức độ hiệu quả của tài liệu
Mặc dù có nhiều câu hỏi mà chúng tôi muốn tìm hiểu, 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à người duy trì dự án nguồn mở tham gia Chương trình viết tài liệu. Ưu tiên hàng đầu của chương trình là hỗ trợ các dự án giải quyết vấn đề về tài liệu.