Dự án Wikimedia Foundation

Trang này chứa thông tin chi tiết về một dự án viết nội dung kỹ thuật đã được chấp nhận tham gia Google Season of Docs.

Tóm tắt dự án

Tổ chức nguồn mở:
Quỹ Wikimedia
Người viết nội dung kỹ thuật:
Pavithra Eswaramoorthy
Tên dự án:
Cải thiện tài liệu dành cho các nhà quay phim và nhà làm phim tài liệu kỹ thuật của Wikimedia
Thời lượng dự án:
Thời hạn tiêu chuẩn (3 tháng)

Mô tả dự án

1. Giới thiệu về bản thân

Tôi được giới thiệu về phần mềm nguồn mở vài tháng trước và gần như ngay lập tức cảm thấy bị choáng ngợp bởi phạm vi vô hạn của phần mềm này. Trong quá trình tìm hiểu hàng tỷ dự án, tôi đã tìm hiểu về các sáng kiến nguồn mở như Google Summer of Code và Outreachy. Google Season of Docs có vẻ thú vị và các ý tưởng dự án của Quỹ Wikimedia đã kích thích sự tò mò của tôi, vì vậy, tôi bắt đầu tìm hiểu thêm.

Từ trước đến nay, hành trình của tôi đều có những đoạn thú vị và đầy bối rối, chẳng hạn như "Chờ, cái gì cơ?", "Ah, tôi hiểu rồi!" và "Tôi có nên bình luận về vấn đề này không?". Cộng đồng Wikimedia luôn ủng hộ tôi ở mọi bước. Từ việc chỉnh sửa trang đến tạo tiện ích, tôi đều học được điều mới mỗi ngày.

Như dự kiến, quy trình đăng ký đã trở thành cánh cửa đưa tôi vào cộng đồng nguồn mở. Đề xuất này được lấy cảm hứng từ chính trải nghiệm của tôi khi mới bắt đầu.

2. Dự án

2.1. Đường viền

Dự án này nhằm cải thiện tài liệu dành cho người viết nội dung kỹ thuật và chuyên gia quay phim tiềm năng trên Wikimedia. Một bộ nguyên tắc tài liệu kỹ thuật hoàn chỉnh sẽ giúp cải thiện tài liệu tổng thể, đồng thời các tài liệu tham khảo để tạo bản ghi màn hình sẽ giúp minh hoạ hiệu quả các tính năng của phần mềm. Chúng tôi có thể mở rộng tài liệu hiện có trong những lĩnh vực này để hỗ trợ tốt hơn cho cả người mới và những người đóng góp dày dặn kinh nghiệm. Một phương pháp tiếp cận dần dần sẽ được áp dụng để phát triển mạng lưới các tài nguyên hữu ích này.

2.2. Thành phẩm

  • T197006 [https://phabricator.wikimedia.org/T197006] – Cải thiện tài liệu cho các nhà làm phim tài liệu của Wikimedia:

    • Thêm các mẹo và ví dụ vào Tài liệu/Hướng dẫn về kiểu. [https://www.mediawiki.org/wiki/Documentation/Style_guide]
    • Thêm thông tin cụ thể về MediaWiki vào một số thể loại nhất định trong các mẫu và đề xuất về Tài liệu kỹ thuật: Hướng dẫn sử dụng, hướng dẫn cách làm, hướng dẫn bắt đầu nhanh, ghi chú phát hành và README. [https://www.mediawiki.org/wiki/Technical_documentation_templates_and_suggestions]
    • Kiểm thử và cải thiện các nguyên tắc ưu tiên Tài liệu kỹ thuật. [https://www.mediawiki.org/wiki/Technical_documentation_prioritization]
    • Thiết kế chiến lược thu thập nội dung cho nhiều thể loại tài liệu.
    • Thiết kế chiến lược giao tiếp và cộng tác cho tài liệu của MediaWiki.
    • Tạo danh sách kiểm tra để các nhà văn có thể xem lại tài liệu của họ trước khi xuất bản.
    • Mở rộng cấu trúc tài liệu cho các nhà văn kỹ thuật mới. [https://www.mediawiki.org/wiki/User:Pavithraes/Sandbox/New_Technical_Writers]
    • Tuyển chọn danh sách các nhiệm vụ liên quan đến tài liệu kỹ thuật phù hợp cho các cuộc thi hackathon. [https://www.mediawiki.org/wiki/Technical_Documentation_Tasks_for_Hack-a-thons]
    • Tạo một trung tâm dành cho người viết nội dung kỹ thuật, trong đó có các tài nguyên hữu ích.

  • Cải thiện tài liệu dành cho nhà quay phim của MediaWiki:

    • Tạo hướng dẫn nhanh cho người dùng về cách tạo bản ghi màn hình chung.
    • Thiết kế các mẫu bản ghi màn hình dành riêng cho MediaWiki cho hướng dẫn và hướng dẫn.

  • T214522 [https://phabricator.wikimedia.org/T214522] – Tạo video ghi lại chuyển động trên màn hình về chủ đề "Giới thiệu về Phabricator".

2.3. Mục tiêu giãn cơ

  • Kiểm tra lại nội dung và cập nhật tài liệu về WikiProject Screencast. (https://en.wikipedia.org/wiki/Wikipedia:WikiProject_Screencast)

3. Cố vấn

Zulip sẽ là phương thức giao tiếp chính với các cố vấn của tôi. Các kênh IRC và email của Wikimedia sẽ được dùng để thảo luận với cộng đồng. Các cuộc thảo luận về các nhiệm vụ cụ thể sẽ diễn ra trong phần nhận xét của các nhiệm vụ trên Phabricator.

4. Thảo luận

Dự án này được chia thành hai giai đoạn:

(i) Cải thiện tài nguyên hiện có cho người viết nội dung kỹ thuật của Wikimedia.

(ii) Tạo các mẫu hữu ích cho những nhà quay phim tiềm năng.

(i) Cải thiện tài nguyên hiện có cho các nhà văn kỹ thuật của Wikimedia.

Trước đây, đã có một số sáng kiến để cải thiện tài liệu của MediaWiki với mức độ thành công khác nhau. Một số ví dụ:

  • https://www.mediawiki.org/wiki/User:Zakgreant/Tech_DocsPlan(2011--01/P6M)
  • https://www.mediawiki.org/wiki/User:Zakgreant/MediaWiki_Technical_Documentation_Plan
  • https://www.mediawiki.org/wiki/Thread:Project:Current_issues/RestructureMediaWiki.org(or:_Document_how_it_was_and_execute_it)
  • https://www.mediawiki.org/wiki/User:Waldir/Docs

Từ những nỗ lực này, chúng tôi có thể hiểu rằng một bộ tài nguyên tốt hơn dành cho người viết nội dung kỹ thuật sẽ có tác động trực tiếp đến các tài liệu mà họ tạo ra.

Dưới đây là một đoạn trích từ báo cáo hai tuần một lần của Anna e só, một thực tập sinh tham gia chương trình Outreachy 2018, tại https://anna.flourishing.stream/2018/01/18/bringing-documentation-to-light/:

"Hướng dẫn quy tắc của MediaWiki chưa hoàn hảo, đặc biệt là vì hướng dẫn này quá phụ thuộc vào các tài liệu tham khảo bên ngoài mà không nêu rõ những phương pháp mà hướng dẫn này coi là tốt nhất. Rất tiếc, đây không phải là vấn đề chỉ xảy ra với MediaWiki, mà còn xuất hiện trên các tài liệu khác như các phương pháp hay nhất về bản dịch. Nhà văn không có tài nguyên tốt và đáng tin cậy để làm việc, dẫn đến khó khăn trong việc thiết lập đối tượng mục tiêu và phong cách viết phù hợp. Và người dùng, đặc biệt là người dùng mới, có thể gặp vấn đề trong việc hiểu các khái niệm và quy trình mới.”

T197006 [https://phabricator.wikimedia.org/T197006] cũng làm sáng tỏ một số lĩnh vực tài liệu viết kỹ thuật cần cải thiện. Rõ ràng là Documentation/Style_guide là nơi để bắt đầu.

Sau khi chúng tôi có hướng dẫn về phong cách tốt hơn, bộ tài liệu tiếp theo sẽ hướng dẫn các nhà văn kỹ thuật thông qua các giai đoạn viết kỹ thuật. Tài liệu cần thân thiện với người mới bắt đầu và đồng thời cung cấp tất cả thông tin cần thiết để người viết tham khảo lại.

Giai đoạn chuẩn bị có thể là quan trọng nhất vì nó đặt nền tảng cho việc xây dựng tài liệu. Để hỗ trợ các nhà văn kỹ thuật trong giai đoạn này, tài liệu tham khảo được phát triển mô tả một số cách hiệu quả để thu thập thông tin liên quan và mẹo về cách sắp xếp thông tin này bằng các mẫu.

Sau đó là bước viết. Tác giả có các ví dụ về tác phẩm hay để tự động đặt ra tiêu chuẩn cao. Ngoài ra, một danh sách kiểm tra được tạo bằng một bộ tiêu chí cơ bản mà mọi tài liệu phải tuân thủ. Điều này sẽ hỗ trợ người viết xem xét tài liệu của họ trước khi xuất bản.

Ngay cả khi có những tài liệu này, các nhà văn kỹ thuật mới vẫn cần được trợ giúp thêm và chúng tôi cần cung cấp sự trợ giúp đó. Hướng dẫn dành cho người mới viết nội dung kỹ thuật được tinh chỉnh và danh sách các nhiệm vụ phù hợp với các cuộc thi lập trình được tuyển chọn dựa trên mức độ khó.

Cuối cùng, tài liệu để hiểu quy trình quản lý và duy trì tài liệu "Ưu tiên tài liệu kỹ thuật" được thử nghiệm và cải thiện.

Vào cuối giai đoạn này, chúng tôi sẽ thiết lập một trung tâm hướng dẫn, tài nguyên, ví dụ, đề xuất và mẫu viết nội dung kỹ thuật để hỗ trợ hướng dẫn về phong cách tài liệu.

(ii) Tạo các mẫu hữu ích cho những nhà quay video tiềm năng.

“Một trong những cách khó nhất để tìm hiểu bất cứ điều gì liên quan đến đồ hoạ là đọc văn bản thuần tuý. Hãy tưởng tượng điều gì sẽ xảy ra nếu hướng dẫn của bạn đề cập đến phiên bản phần mềm không chính xác – với hướng dẫn chỉ có văn bản, thường thì bạn không thể tạo lại một loạt thao tác khi trình đơn và cách diễn đạt trong ứng dụng thay đổi vì chúng ta thiếu tất cả các tín hiệu mà chúng ta thường sử dụng.

Có lẽ cách tốt nhất để tìm hiểu là khi có một chuyên gia ngồi ngay bên cạnh bạn. Bản ghi màn hình nằm giữa đồ hoạ tĩnh và việc có một chuyên gia bên cạnh. Chúng ta có một bản minh hoạ trực quan, sống động với giọng nói thân thiện, chúng ta cũng có thể có chú thích văn bản trên màn hình và ảnh động. Một lợi thế của bản ghi màn hình so với chuyên gia là bạn có thể phát lại bản ghi màn hình bất cứ lúc nào trong ngày.

Chúng tôi cũng có thể thêm phụ đề đã dịch vào bản ghi màn hình để những người không nói tiếng bản địa có thể xem hoặc thay thế bản âm thanh bằng ngôn ngữ khác".

Trong đoạn trích trên từ ""Cẩm nang ghi màn hình"" [https://thescreencastinghandbook.com/wp-content/uploads/The_Screencasting_handbook_rel10_20100502_v6.pdf], Ian Ozsvald giải thích tầm quan trọng của ghi màn hình. Nó có thể đặc biệt hữu ích đối với các hướng dẫn về cách thiết lập môi trường phát triển MediaWiki, viết tiện ích mở rộng, sử dụng Gerrit và nhiều hướng dẫn khác.

Tương tự như các mẫu cho tài liệu, việc có một mẫu chuẩn cho bản ghi màn hình sẽ giúp tăng tính đồng nhất, từ đó cải thiện trải nghiệm của người xem. Ứng dụng này cũng cung cấp cho các nhà quay phim tiềm năng một khung để bắt đầu. Do đó, chúng tôi đã phát triển một hướng dẫn nhanh cho người dùng, sau đó là các mẫu để tạo video giới thiệu và hướng dẫn. Các tài liệu này bao gồm các gợi ý về chiều sâu của các khái niệm sẽ được đề cập và một số ý tưởng ghi lại chuyển động trên màn hình cho MediaWiki.

Cách tốt nhất để kiểm thử mẫu trên và chuẩn bị cho mục tiêu mở rộng là tạo bản ghi màn hình bằng các công cụ và mẫu. Do đó, một bản ghi màn hình "Giới thiệu về Phabricator" sẽ được tạo để trình bày các kiến thức cơ bản về cách sử dụng Phabricator. Quy trình này cũng sẽ làm nổi bật những khía cạnh cần thảo luận.

Cuối cùng, nguồn tài liệu tham khảo chính dành cho các nhà quay phim của Wikimedia – WikiProject Screencast đã được xem xét và cập nhật.

5. Tiến trình dự kiến

Giai đoạn gắn kết cộng đồng (1/8 – 1/9)

  • Phân tích chi tiết dự án với các cố vấn của tôi.

  • Thảo luận về:

    • Tần suất xem xét các nhiệm vụ.
    • Chia sẻ lịch biểu và quyết định quy trình làm việc hằng tuần/hằng ngày.
    • Các công cụ và tài nguyên có thể sử dụng.
    • Báo cáo dự án hằng ngày và 2 tuần một lần.

  • Tạo các việc cần làm và việc cần làm phụ bắt buộc trên Phabricator.

  • Tạo bản thảo để bù đắp cho những cam kết cá nhân trong giai đoạn xây dựng tài liệu.

Tuần 1 (2 – 8 tháng 9)

  • Cải thiện Documentation/Style_guide:

    • Chuyển trọng tâm chính để minh hoạ các phương pháp và tiêu chuẩn hay nhất trên MediaWiki.
    • Đưa vào các ví dụ về công việc chất lượng và cải thiện khả năng hiển thị của các trang liên kết.

  • Cải thiện hướng dẫn dành cho Người viết nội dung kỹ thuật mới:

    • Mở rộng cấu trúc tài liệu.

Tuần 2 (9/9 — 15/9)

  • Làm việc về việc ưu tiên tài liệu kỹ thuật:

    • Đánh giá bảng công việc tài liệu; tìm ví dụ về nội dung mô tả và mức độ ưu tiên tốt cho công việc.
    • Nghiên cứu các xu hướng và ghi lại những khó khăn thường gặp.
    • Sử dụng thông tin và ví dụ để ghi lại các tiêu chuẩn ưu tiên.

Tuần 3 (16/9 – 22/9)

  • Tạo các tài liệu bổ sung sau đây cho người viết tài liệu kỹ thuật:

    • Danh sách kiểm tra để giúp bạn xem lại tài liệu kỹ thuật trước khi xuất bản.
    • Các cách thu thập nội dung hiệu quả cho nhiều thể loại tài liệu.

Tuần 4 (23/9 – 29/9)

  • Thêm thông tin về cách viết ở các thể loại MediaWiki phổ biến nhất vào mẫu tài liệu và đề xuất về kỹ thuật:

    • Ghi lại các phương pháp hay nhất trên MediaWiki để viết hướng dẫn sử dụng, tài liệu hướng dẫn bắt đầu nhanh, tệp README, ghi chú phát hành và tài liệu hướng dẫn.

  • Thêm hướng dẫn để cải thiện mức độ hoàn thiện của thông tin trao đổi kỹ thuật. [https://www.mediawiki.org/wiki/User:SRodlund_(WMF)/Maturity_model_for_MediaWiki_technical_documentation#Increasingmaturity--_strategic_directions]

Tuần 5 (30/9 – 6/10)

  • Cải thiện tài liệu hướng dẫn cộng tác viên mới:

    • Cập nhật trang: Tác vụ tài liệu kỹ thuật cho hackathon. (Việc cần làm: Thêm các nhiệm vụ phù hợp vào trang này trong suốt thời gian dự án)

  • Xây dựng trung tâm dành cho người viết nội dung kỹ thuật

    • Tạo trang đích có đường liên kết đến các trang và tài nguyên hữu ích.
    • Thêm các đường liên kết cần thiết vào các trang mới và trang hiện có để dễ dàng điều hướng giữa các trang đó.

Tuần 6 (7/10 – 13/10)

  • Tạo các tài liệu sau đây về cách tạo video cho MediaWiki:

    • Hướng dẫn nhanh cho người dùng về cách "tạo bản ghi màn hình chung", trong đó có đường liên kết đến Dự án bản ghi màn hình.
    • Mẫu dành cho: Hướng dẫn sử dụng phần mềm/công cụ; Hướng dẫn phát triển các công cụ mới.

  • Tạo danh sách các ý tưởng về bản ghi màn hình cho MediaWiki.

Tuần 7 (14 – 20 tháng 10)

  • Làm việc trên video ""Giới thiệu về Phabricator"":

    • Sử dụng mẫu (được tạo vào tuần trước đó) để nháp tập lệnh.
    • Ước tính hiệu quả của mẫu và cải thiện mẫu nếu cần.
    • Nhận ý kiến phản hồi và hoàn thiện bản nháp.

Tuần 8 (21/10 – 27/10)

  • Xuất bản video "Giới thiệu về Phabricator":

    • Chọn và cài đặt phần mềm.
    • Thiết lập môi trường và tạo bản ghi màn hình.
    • Ghi lại các vấn đề gặp phải và giải pháp.

Tuần 9 (28 tháng 10 – 3 tháng 11)

  • Cải thiện tài liệu về dự án Video ghi lại chuyển động trên màn hình:

    • Kiểm tra cấu trúc và thảo luận về mọi thay đổi cần thiết.
    • Xem xét các phần mềm được đề cập.
    • Nghiên cứu và cập nhật danh sách phần mềm.

Tuần 10 (4/11 — 10/11)

  • Tiếp tục cải thiện tài liệu về dự án Bản ghi màn hình:

    • Đánh giá và cải thiện hướng dẫn cũng như tập lệnh.
    • Xem lại thư viện bản ghi màn hình.

Tuần 11 (11/11 – 17/11)

  • Hoàn thành bài tập trong tài liệu về dự án Screencast:

    • Tìm và thêm các video mới hơn vào thư viện.
    • Thực hiện những thay đổi cấu trúc cần thiết.

Tuần 12 (18/11 – 24/11)

  • Làm việc trên mọi việc cần làm đang chờ xử lý.

  • Viết báo cáo cuối cùng:

    • Tham khảo báo cáo hằng tuần/hằng ngày và thu thập thông tin cần thiết.
    • Lập kế hoạch cho cấu trúc báo cáo và viết bản nháp.
    • Cải thiện và hoàn thiện bản thảo dựa trên ý kiến phản hồi của người cố vấn.

Tuần 13 (25/11 – 29/11)

  • Gửi báo cáo cuối cùng và đánh giá của người cố vấn.

6. Theo dõi tiến trình

Tôi sẽ thông báo cho người hướng dẫn về tiến trình hằng ngày thông qua Zulip. Cộng đồng Wikimedia có thể theo dõi tiến trình của tôi thông qua Phabricator hoặc báo cáo dự án hai tuần một lần.

7. Cam kết khác

Tôi là sinh viên đại học toàn thời gian và học kỳ mùa thu của tôi trùng với tiến trình của Chương trình mùa Tài liệu. Do đó, tôi có các cam kết liên quan đến các kỳ thi đại học.

Bài kiểm tra nội bộ đầu tiên: Từ ngày 18 đến ngày 24 tháng 8

Bài kiểm tra nội bộ thứ hai: Từ ngày 29 tháng 9 đến ngày 6 tháng 10

Kỳ thi cuối học kỳ: từ ngày 11/11 đến ngày 30/11

Tôi cũng dự định tham dự hội nghị công khai đầu tiên của mình, PyCon India từ ngày 12 đến ngày 15 tháng 10, nhờ địa điểm thuận lợi trong năm nay. Tôi tin rằng đây sẽ là một cơ hội tuyệt vời để gặp gỡ những người mới và có những cuộc trò chuyện sâu sắc.

Để quản lý các cam kết này, tiến trình dự kiến sẽ chứa các việc cần làm ít quan trọng hơn trong những tuần tương ứng. Tôi dự định hoàn thành không quá 20 tín chỉ cốt lõi trong học kỳ mùa thu để có đủ thời gian phát triển tài liệu. (Một học viên thông thường hoàn thành trung bình 25 tín chỉ mỗi học kỳ)