Giai đoạn hiện tại:
Chương trình Season of Docs 2021 đã kết thúc vào ngày 14 tháng 12 năm 2021. Xem tiến trình.
Hãy sử dụng ví dụ này để tạo báo cáo nghiên cứu điển hình của riêng bạn.
PicklePlus: Ghi lại công cụ đóng góp GloriousPickle
Tổ chức hoặc dự án: Glorious Pickle đường liên kết đến trang web chính của tổ chức hoặc dự án của bạn tại đây
Nội dung mô tả về tổ chức: GloriousPickle (phiên bản hiện tại là 1.2.3, bản phát hành đầu tiên vào năm 2009) là một thư viện được MIT cấp phép để dễ dàng tính toán tỷ lệ muối, đường, giấm và gia vị hoàn hảo cho mọi loại rau có thể làm dưa chua, với số lượng từ một quả dưa chuột nhỏ đến một container chở đầy củ cải.
Tác giả: không bắt buộc: liệt kê tác giả của nghiên cứu điển hình; sử dụng tên người dùng nếu được yêu cầu
Tuyên bố vấn đề/Tóm tắt đề xuất
Bạn đang cố gắng giải quyết vấn đề gì bằng tài liệu mới hoặc được cải thiện? Liên kết đến trang đề xuất trên trang web dự án của bạn (nếu có thể).
Việc thêm nguyên liệu vào cơ sở dữ liệu nguyên liệu của công cụ GloriousPickle tốn nhiều thời gian và phức tạp, đồng thời công cụ này không có tài liệu đầy đủ. Nhiều người muốn đóng góp không có kinh nghiệm sử dụng git hoặc tạo yêu cầu kéo. Điều này có nghĩa là GloriousPickle có những thiếu sót nghiêm trọng trong dữ liệu thành phần, khiến công cụ của chúng ta kém hữu ích. Bằng việc cải thiện tài liệu về cách thêm nguyên liệu mới, chúng tôi hy vọng sẽ khuyến khích được cộng tác viên mới và nhiệt huyết hơn nữa!
Mô tả dự án
Tạo đề xuất
Bạn đã nghĩ ra đề xuất về Mùa tài liệu như thế nào? Tổ chức của bạn đã sử dụng quy trình nào để quyết định một ý tưởng? Bạn đã thu thập và đưa ý kiến phản hồi vào dự án như thế nào?
Nhóm đặc nhiệm PickleDocs của GloriousPickle đã biết về chương trình Mùa tài liệu thông qua một tweet của Văn phòng chương trình nguồn mở của Google. SIG đã thảo luận về chương trình này tại cuộc họp hai tuần một lần và thống nhất soạn thảo một đề xuất. Hai thành viên của SIG (@KimChiCook và @Dillicious) đã tình nguyện soạn thảo bản đề xuất dự thảo để được xem xét trong cuộc họp tiếp theo.
Sau khi PickleDocs SIG đồng ý với bản dự thảo đề xuất, một email đã được gửi đến dự án rộng hơn để yêu cầu phản hồi. 14 thành viên trong cộng đồng đã đưa ra ý kiến phản hồi, trong đó có @GloriousPicklePat, người duy trì API thêm thành phần. @GloriousPicklePat đã tình nguyện trở thành một nguồn hỗ trợ trong chương trình.
Sau khi thảo luận và đưa ý kiến phản hồi vào, đề xuất này đã được gửi đến Ủy ban điều hành dự án GloriousPickle để bỏ phiếu. Cả 5 thành viên của GPPSC đều đồng ý gửi đề xuất và đơn đăng ký. @VinegarViv cũng đồng ý giúp tạo tài khoản Open Collective cần thiết để tham gia chương trình và giám sát các khoản thanh toán.
Ngân sách
Thêm một phần ngắn về ngân sách của bạn. Bạn đã ước tính công việc này như thế nào? Có chi phí nào ngoài dự kiến không? Bạn có chi tiêu ít hơn số tiền được cấp không? Bạn có thể sử dụng các khoản tiền khác ngoài Season of Docs không?
Hai thành viên của GloriousPickle PickleDocs SIG) đều là người viết bài về kỹ thuật (một ở Châu Âu và một ở Argentina). Họ đã giúp chúng tôi ước tính công việc và tìm ngân sách dự án tương tự, so sánh với công việc đề xuất dự thảo mà họ đã thực hiện trước đó. Chúng tôi cũng còn 1.000 đô la Mỹ tiền tài trợ không ràng buộc từ hội nghị PicklePals năm 2019 và đã phân bổ số tiền này cho dự án.
Một khoản chi phí ngoài dự kiến là giúp nhà văn kỹ thuật của chúng tôi thuê một điểm phát sóng Wi-Fi vì họ đang ở một khu vực chịu ảnh hưởng của đám cháy rừng và mất kết nối Internet tại nhà. Cuối cùng, chúng tôi cũng gửi ít áo phông hơn dự kiến cho người tham gia, nên mọi thứ đã cân bằng.
Ngoài ra, chúng tôi quyết định bồi thường cho một cộng tác viên của GloriousPickle, @Piccalily (từng là một biên tập viên chuyên nghiệp trong cuộc sống ngoài Pickle) để giúp biên tập và hiệu đính tài liệu do nhà văn kỹ thuật tạo.
Người tham gia
Ai đã làm việc trong dự án này (sử dụng tên người dùng nếu người tham gia yêu cầu)? Bạn đã tìm và thuê người viết tài liệu kỹ thuật bằng cách nào? Bạn đã tìm thấy những người tình nguyện hoặc người tham gia có trả phí khác bằng cách nào? Họ có những vai trò gì? Có ai đã thôi làm hội viên không? Bạn đã học được gì về việc tuyển dụng, giao tiếp và quản lý dự án?
Nhóm cốt lõi làm việc trên dự án này bao gồm:
- @Dillicious, @KimChiCook (PickleDocs SIG)
- @Piccalily (người biên tập nội dung)
- @GherKen, @VinegarViv (trợ giúp quản trị viên, GPPSC)
- @BBChips, @GloriousPicklePat (các chuyên gia chủ đề)
- Sam Scribe (nhân viên viết tài liệu kỹ thuật)
Chúng tôi tìm thấy Sam Scribe thông qua danh sách Kho lưu trữ GitHub của Season of Docs. Chúng tôi cho rằng kinh nghiệm của họ (Sam từng làm việc cho một tạp chí ẩm thực cũng như viết tài liệu cho các trang web) rất phù hợp với dự án của chúng tôi. Sam đã tham gia cuộc gọi hai tuần một lần của PickleDocs SIG và nói chuyện về dự án với chúng tôi, đưa ra một số đề xuất rất có giá trị mà chúng tôi đã đưa vào đề xuất này. Chúng tôi cũng đã liên hệ với hai nhà văn kỹ thuật khác mà chúng tôi biết thông qua mạng lưới của thành viên SIG, nhưng cả hai đều không có mặt trong khoảng thời gian diễn ra chương trình.
Do múi giờ của Sam chỉ chồng chéo khoảng vài giờ với hầu hết thành viên của PickleDocs SIG, chúng tôi đã gửi một cuộc gọi trong diễn đàn thảo luận của mình cho những Người chọn múi giờ ở múi giờ của Sam và quen thuộc với quy trình thêm nguyên liệu. @BBChips đã tình nguyện trả lời câu hỏi cho Sam và giúp họ tìm các chuyên gia khác nếu cần. @GloriousPicklePat cũng tình nguyện giúp Sam hiểu được cấu trúc cơ bản của công cụ và thông báo lỗi có thể xảy ra từ API, đồng thời hỗ trợ về GitHub và git.
Rất tiếc, giữa chừng @VinegarViv đã phải rút lui khỏi dự án vì lý do cá nhân. Thành viên @GherKen của GPPSC đã đứng ra xử lý các câu hỏi về việc thanh toán và hành chính.
Sau khi bỏ lỡ một số câu hỏi (GloriousPickle sử dụng một phiên bản Slack miễn phí và đôi khi cuộc thảo luận diễn ra quá nhanh khiến chúng tôi mất các cuộc trò chuyện do giới hạn lưu trữ luân phiên), chúng tôi nhận thấy rằng mình nên giữ danh sách các câu hỏi đang diễn ra trong một tài liệu dùng chung (chúng tôi đã sử dụng Google Tài liệu dùng chung). Các thành viên PickleTài liệu SIG đã kiểm tra tài liệu này trước mỗi cuộc họp và đảm bảo họ nhận được câu trả lời trước khi kết thúc cuộc họp. Sam có thể nhắn tin trực tiếp cho @BBChips để hỏi những câu hỏi cấp bách.
Chúng tôi rất vui khi được làm việc với Sam. Ngoài việc cập nhật tài liệu về GloriousPickle, Sam còn trở thành một người rất thích dùng pickle!
Dòng thời gian
Trình bày ngắn gọn tiến trình của dự án (cho biết ngày kết thúc dự kiến hoặc các mốc trung gian nếu dự án đang diễn ra).
Trong khi chờ chương trình Season of Docs công bố các tổ chức tham gia, các thành viên của Nhóm đặc nhiệm PickleDocs đã tìm kiếm mọi công việc trước đây mà chúng tôi cho rằng sẽ hữu ích cho Sam. Trong vòng một tháng, chúng tôi đã tìm thấy một số ghi chú từ nỗ lực cập nhật tài liệu trước đó đã bị đình trệ, đồng thời chúng tôi cũng đã xem xét một số tài liệu kiểm tra mức độ trưởng thành của tài liệu trong kho lưu trữ opendocs của Google.
Sau khi nhận được tin vui rằng chúng tôi đã được chọn tham gia Chương trình Season of Docs 2021, Sam và Nhóm đặc nhiệm PickleDocs đã gặp mặt và lên lịch sơ bộ:
| Sân khấu | Người hoàn thành |
|---|---|
| Kiểm tra tài liệu xem xét | Ngày 7 tháng 5 |
| Trường hợp sử dụng nhật ký ma sát 3 | Ngày 14 tháng 5 |
| Xem lại nhật ký ma sát với @GloriousPicklePat và @BBChips, trả lời truy vấn | Ngày 28 tháng 5 |
| Bản nháp đầu tiên của trường hợp sử dụng 1 trong tài liệu cập nhật | Ngày 25 tháng 6 |
| Bản thảo trường hợp sử dụng 1 do @GloriousPicklePat và @KimChiCook xem xét | Ngày 2 tháng 7 |
| Bản nháp đầu tiên của trường hợp sử dụng tài liệu cập nhật 2 | Ngày 2 tháng 7 |
| Bản thảo trường hợp sử dụng 2 do @GloriousPicklePat và @Dillicious xem xét | Ngày 9 tháng 7 |
| Bản nháp đầu tiên của trường hợp sử dụng tài liệu cập nhật 3 | Ngày 9 tháng 7 |
| Trường hợp sử dụng 3 bản nháp do @Dillicious và @KimChiCook xem xét | Ngày 16 tháng 7 |
| Mọi câu hỏi được trả lời cho mọi trường hợp sử dụng | Ngày 30 tháng 7 |
| Hầu hết các thành viên SIG PickleDocs đều nghỉ phép từ ngày 1 đến ngày 20 tháng 8 | -- |
| Bắt đầu thử nghiệm tài liệu mới trong cộng đồng (tài liệu được xuất bản dưới dạng bản nháp trên trang web GloriousPickle) | Ngày 21 tháng 8 |
| Đã đưa ý kiến phản hồi về thử nghiệm vào | Ngày 10 tháng 9 |
| Biên tập và hiệu đính tài liệu mới | Ngày 17 tháng 9 |
| Xoá trạng thái nháp của tài liệu, tài liệu được ra mắt chính thức | Ngày 28 tháng 9 |
| Quy trình cập nhật tài liệu đã tạo | Ngày 1 tháng 11 |
| Nghiên cứu điển hình này đã được tạo | Ngày 8 tháng 11 |
| Đã gửi nghiên cứu điển hình | Ngày 16 tháng 11 |
Trong ngân sách đề xuất, chúng tôi đã ước tính rằng nhà văn kỹ thuật sẽ dành 10 đến 15 giờ mỗi tuần để làm việc trên dự án của chúng tôi. Sam đã ghi lại thời gian và trung bình là 11,5 giờ mỗi tuần.
Kết quả
Điều gì đã được tạo, cập nhật hoặc thay đổi? Đưa vào các đường liên kết đến tài liệu đã xuất bản (nếu có). Có sản phẩm nào trong đề xuất không được tạo không? Hãy liệt kê cả những ứng dụng đó.
Ba trường hợp sử dụng chính được ghi lại cùng với hướng dẫn đầy đủ về cách sử dụng cho người dùng:
Cách thêm một thành phần mới vào GloriousPickle
Cách thêm thành phần biến thể vào GloriousPickle
Cách cập nhật hoặc chỉnh sửa một thành phần trong GloriousPickle
Các hướng dẫn này cũng bao gồm các mẫu yêu cầu kéo mới để giúp bạn dễ dàng đóng góp hơn.
Ngoài ra, trong dự án này, Sam đã tạo một Bảng chú giải thuật ngữ nhỏ về các thuật ngữ mà họ học được từ Pickle. Những thuật ngữ này cũng được xuất bản trên trang web của dự án GloriousPickle.
Chúng tôi đã thêm hướng dẫn cập nhật các hướng dẫn cách làm này cho người dùng vào wiki dự án.
Chúng tôi đã bao gồm việc tạo một bản tóm tắt cho những người đóng góp mới sử dụng GitHub để giúp họ sử dụng các quy trình và công cụ của chúng tôi. Tuy nhiên, khi xem xét những tài nguyên hiện có, chúng tôi có thể phát triển bản tóm tắt của một dự án khác.
Chỉ số
Bạn đã chọn những chỉ số nào để đo lường mức độ thành công của dự án? Bạn có thu thập được những chỉ số đó không? Các chỉ số có tương quan tốt hay không tốt với kết quả mà bạn muốn đạt được cho dự án? Các chỉ số của bạn có thay đổi kể từ khi bạn đề xuất không?
Trong đề xuất của mình, chúng tôi đã đề xuất hai chỉ số:
- số lượng yêu cầu lấy thông tin liên quan đến nguyên liệu
- số lượng yêu cầu kéo từ người đóng góp mới
Trong tháng 9 (tháng đầu tiên kể từ khi phát hành tài liệu nháp), chúng tôi nhận thấy số lượng yêu cầu lấy dữ liệu liên quan đến thành phần tăng 5% (từ 20 yêu cầu vào tháng 8 lên 21 yêu cầu vào tháng 9) và có 3 cộng tác viên mới đã gửi tổng cộng 4 yêu cầu lấy dữ liệu (so với 2 cộng tác viên mới đã gửi 2 yêu cầu lấy dữ liệu vào tháng 8). Chúng tôi dự định theo dõi các chỉ số này hằng tháng.
Kể từ ngày 1 tháng 1, chúng tôi cũng sẽ theo dõi số lượng cộng tác viên đã đóng góp tổng cộng hơn 3 nội dung, bắt đầu từ quý sau khi tài liệu được xuất bản.
Có kinh nghiệm, chúng tôi tin rằng tài liệu mới này đã tạo ra sự khác biệt trong việc cho phép những người đóng góp mới thêm vào cơ sở dữ liệu về nguyên liệu của GloriousPickle — một người đóng góp mới được nhắc đến trong phần bình luận về quảng cáo của họ mà họ từng thử nhưng chưa hoàn tất việc cập nhật vì họ không hiểu quy trình thực hiện.
Phân tích
Điều gì đã diễn ra suôn sẻ? Điều gì nằm ngoài dự kiến? Bạn đã gặp phải những trở ngại hoặc khó khăn gì? Bạn có cho rằng dự án của mình đã thành công không? Tại sao (hoặc tại sao lại không)? (Nếu còn quá sớm để đánh giá, hãy giải thích thời điểm bạn dự kiến có thể đánh giá mức độ thành công của dự án.)
Chúng tôi rất hài lòng với kết quả của dự án Phần tài liệu và coi đó là một thành công. Tài liệu mới rất rõ ràng và hữu ích. Chúng tôi đã nhận thấy số lượng yêu cầu kéo liên quan đến thành phần và số lượng yêu cầu kéo của các cộng tác viên mới tăng lên đáng kể.
Chúng tôi cũng rất vui khi gần như toàn bộ cộng đồng GloriousPickle đã tham gia, thông qua việc đưa ra ý kiến phản hồi về đề xuất ban đầu và kiểm thử tài liệu mới ở dạng bản nháp.
Chúng tôi đã gặp phải một số trở ngại ngoài dự kiến. Chúng tôi rất cảm ơn vì đám cháy rừng ở tiểu bang của Sam không gây ra thiệt hại nào ngoài việc mất Internet! Ngoài ra, chúng tôi rất tiếc khi mất @VinegarViv trong dự án này; chúng tôi chúc cô ấy và gia đình những điều tốt đẹp nhất và hy vọng sớm gặp lại cô ấy.
Một điều mà chúng tôi không nhận ra cho đến khi Sam bắt đầu làm việc trên tài liệu là có bao nhiêu thuật ngữ và từ viết tắt liên quan đến dưa chuột sẽ lạ lẫm với những người bước vào dự án của chúng tôi mà không có bối cảnh phổ biến. Tuy nhiên, Sam đã ghi lại danh sách mọi thuật ngữ lạ và xác định các thuật ngữ đó thông qua nghiên cứu của riêng mình cũng như nhờ các thành viên trong cộng đồng giải thích và tham khảo. Từ điển thuật ngữ về Pickle này sẽ giúp ích rất nhiều trong việc thu hút thêm nhiều người tham gia cộng đồng Pickle trong tương lai.
Tóm tắt
Tóm tắt trải nghiệm của bạn về dự án trong 2-4 đoạn văn. Nêu bật những điều bạn đã học được và những việc bạn sẽ chọn làm khác đi trong tương lai. Bạn sẽ đưa ra lời khuyên gì cho các dự án khác đang cố gắng giải quyết vấn đề tương tự về tài liệu?
Tóm lại, chúng tôi đã có trải nghiệm tuyệt vời! Chúng tôi đã hoàn thành các sản phẩm tài liệu và các chỉ số của chúng tôi có vẻ như phù hợp với mục tiêu.
Một phần lớn sự thành công của dự án này là nhờ chúng tôi đã may mắn được làm việc với nhà văn kỹ thuật Sam Scribe. [Tôi không viết phần này – Sam] Mặc dù không có kiến thức về cách lưu trữ hoặc kinh nghiệm sử dụng GitHub, nhưng với tư cách là một nhà văn kỹ thuật giàu kinh nghiệm, Sam đã tự tin tìm hiểu một chủ đề mới, đặt câu hỏi và nghiên cứu. Sam nhanh chóng nắm bắt không chỉ các công cụ dự án của chúng tôi (chúng tôi sử dụng bảng kanban để theo dõi công việc) mà còn cả các câu chuyện cười về dưa chuột muối! Chúng tôi rất vui vì Sam đã bắt được bọ rùa và chúng tôi đã "đóng chai" chúng trong cộng đồng của mình.
Các dự án khác nên:
- Giữ cho đề xuất của bạn nhỏ gọn và dễ quản lý. (Ban đầu, chúng tôi muốn đưa vào tài liệu về việc sử dụng công cụ ước tính với máy móc gắp muối công nghiệp trong đề xuất của mình và chỉ bỏ qua vì một trong các thành viên cộng đồng của chúng tôi tham gia sâu vào máy dưa góp nguồn mở sẽ viết luận văn tiến sĩ của mình trong chương trình.) Cuối cùng, chúng tôi đã có đủ việc để Sam làm!
- Tận dụng mạng lưới của bạn khi tìm kiếm người viết nội dung kỹ thuật. Hãy hỏi mọi người trong cộng đồng của bạn về đề xuất. Mặc dù tìm thấy Sam thông qua GitHub của Season of Docs, nhưng chúng tôi cảm thấy tự tin khi làm việc với họ vì đã trò chuyện với một số người trong thời gian đăng ký.
- Chào mừng nhà văn kỹ thuật đến với cộng đồng của bạn! Sam cho biết rằng thái độ nhiệt tình của GloriousPicklers giúp cô dễ dàng đặt câu hỏi.
- Giúp người viết nội dung kỹ thuật có được kỹ năng về nguồn mở. Sam chưa từng sử dụng git, nhưng sau khi xem một vài hướng dẫn, họ đã nhanh chóng nắm bắt được. Ban đầu, Sam lo lắng về mức độ phản hồi mà họ có thể nhận được từ cộng đồng và cách đưa ý kiến phản hồi đó vào. Tuy nhiên, mô hình "sự đồng thuận thô tục" của cộng đồng ("sự đồng thuận sẽ đạt được khi mọi vấn đề được giải quyết nhưng chưa chắc đã được đáp ứng") đã giúp Sam tự tin giải quyết những lời phê bình bằng kiến thức chuyên môn về kỹ thuật viết của mình.
Phụ lục
Nếu có tài liệu khác muốn liên kết (ví dụ: nếu bạn đã tạo hợp đồng làm việc với người viết tài liệu kỹ thuật mà bạn muốn chia sẻ, hoặc các mẫu cho dự án tài liệu hay các tài nguyên tài liệu mở khác, bạn có thể liệt kê và liên kết chúng tại đây). Phụ lục cũng là nơi phù hợp để liệt kê các đường liên kết đến các công cụ hoặc tài nguyên hỗ trợ tài liệu mà bạn đã sử dụng, hoặc là nơi để gửi lời cảm ơn hoặc lời cảm ơn có thể không phù hợp với các phần trên.
Thư cảm ơn
Nhóm chúng tôi muốn cảm ơn những người và điều sau đây:
- @Dillicious muốn cảm ơn đối tác của mình và đài phát nhạc hip hop chất lượng thấp
- @KimChiCook muốn cảm ơn 할머니 đã dạy anh cách dưa góp
- @Piccalily muốn cảm ơn Chicago Manual of Style Online
- @GherKen muốn cảm ơn 3 đứa con của mình vì đã ăn hết dưa chua mà anh làm
- @VinegarViv muốn cảm ơn các thành viên còn lại trong nhóm đã hỗ trợ cô trong quá trình từ chức
- @BBChips muốn cảm ơn món ăn không phải dưa chua ngon nhất hiện có, đó là bánh quy caramel của Tunnock
- @GloriousPicklePat muốn cảm ơn Nhóm đặc nhiệm PickleDocs đã nhận dự án này
- Sam Scribe muốn cảm ơn toàn thể cộng đồng GloriousPickle, đặc biệt là những người làm dưa chua đã gửi cho họ các lọ đựng thực phẩm đóng hộp trong mùa hè năm 2021 khi thiếu lọ đựng thực phẩm đóng hộp, giúp họ bắt đầu hành trình làm ra nhiều món dưa chua ngon!