Dự án Wikimedia Foundation

Trang này chứa thông tin chi tiết về một dự án viết kỹ thuật được chấp nhận cho Phần Google Tài liệu.

Tóm tắt dự án

Tổ chức nguồn mở:
Quỹ Wikimedia Foundation
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à quay phim kỹ thuật của Wikimedia
Thời lượng dự án:
Thời gian tiêu chuẩn (3 tháng)

Mô tả dự án

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

Tôi đã được giới thiệu 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 đó. Tôi gặp khó khăn khi đi qua các dự án quy mô lớn, tôi tìm hiểu về các sáng kiến nguồn mở như Mùa hè lập trình của Google và Sự tiếp xúc. Phần Tài liệu trên Google có vẻ thú vị và ý tưởng dự án của Wikimedia Foundation đã khơi gợi trí tò mò của tôi, vì vậy, tôi bắt đầu khám phá thêm.

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

Đúng như dự kiến, quy trình đăng ký chính là cổng vào của tôi trong cộng đồng nguồn mở. Đề xuất này được lấy cảm hứng từ kinh nghiệm của chính 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 cho người viết kỹ thuật và nhà quay phim tiềm năng trên Wikimedia. Một bộ nguyên tắc hoàn chỉnh về tài liệu kỹ thuật sẽ giúp cải thiện tài liệu tổng thể, đồng thời tài liệu tham khảo để tạo bản ghi màn hình sẽ giúp minh hoạ các tính năng của phần mềm một cách hiệu quả. Tài liệu hiện có về những lĩnh vực này có thể được mở rộng để hỗ trợ tốt hơn cho cả người mới tham gia và người đóng góp dày dạn kinh nghiệm. Một phương pháp gia tăng sẽ được áp dụng để phát triển mạng lưới 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 dành cho các nhà tài liệu của Wikimedia:

    • Thêm mẹo và ví dụ vào Tài liệu/Hướng dẫn định kiểu. [https://www.mediawiki.org/wiki/Documentation/Style_guide]
    • Thêm thông tin cụ thể trên MediaWiki vào một số thể loại nhất định trong phần gợi ý và mẫu tài liệu kỹ thuật: Hướng dẫn sử dụng, hướng dẫn sử dụng, hướng dẫn bắt đầu nhanh, ghi chú phát hành và tài liệu README. [https://www.mediawiki.org/wiki/Technical_documentation_templates_and_suggestions]
    • Thử nghiệm và cải thiện các nguyên tắc để sắp xếp mức độ ưu tiên cho tài liệu kỹ thuật.
    • 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 liên lạc và cộng tác cho tài liệu của MediaWiki.
    • Tạo danh sách kiểm tra để người viết có thể đánh giá tài liệu của mình trước khi xuất bản.
    • Mở rộng cấu trúc tài liệu cho những người viết nội dung kỹ thuật mới. [https://www.mediawiki.org/wiki/User:Pavithraes/Sandbox/New_Technical_Writers]
    • Sắp xếp danh sách các nhiệm vụ liên quan đến tài liệu kỹ thuật phù hợp với sự kiện hackathon. [https://www.mediawiki.org/wiki/Technical_Documentation_Tasks_for_Hack-a-thons]
    • Tạo trung tâm cho người viết kỹ thuật trỏ đến các tài nguyên hữu ích.

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

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

  • T214522 [https://phabricator.wikimedia.org/T214522] – Tạo bản ghi màn hình “Giới thiệu về Phabricator”.

2.3. Kéo giãn mục tiêu

  • 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. Người cố vấn

Zulip sẽ là phương thức liên lạc 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ề những công việc cụ thể sẽ diễn ra trong phần nhận xét của các công việc của Trình phân phối.

4. Thảo luận

Dự án này thường được chia làm hai giai đoạn:

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

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

(i) Cải thiện các tài nguyên hiện có cho đội ngũ viết thông tin 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 nhiều mức độ thành công. Sau đây là 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

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

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

“Hướng dẫn quy tắc của MediaWiki vẫn chưa hoàn hảo, đặc biệt là do dựa quá nhiều vào các tài liệu tham khảo bên ngoài mà không nêu bật những phương pháp mà MediaWiki coi là tốt nhất. Rất tiếc, vấn đề này không chỉ giới hạn ở MediaWiki, mà còn xuất hiện trong các tài liệu khác, chẳng hạn như Các phương pháp hay nhất cho bản dịch. Để làm được điều đó, người viết thường không có được nguồn lực chất lượng và đáng tin cậy để thực hiện tác phẩm của mình, dẫn đến việc xây dựng được cộng đồng khán giả mục tiêu cũng như 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 phải vấn đề khi 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 nhất định của tài liệu viết kỹ thuật cần cải thiện. Rõ ràng, tài liệu/Style_guide là nơi để bạn bắt đầu.

Sau khi chúng tôi có được hướng dẫn về quy tắc viết hiệu quả hơn, chúng tôi dự định sẽ hướng dẫn các nhà viết nội dung kỹ thuật qua các giai đoạn của việc viết kỹ thuật. Tài liệu cần phải phù hợp với người mới bắt đầu, đồ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ì giai đoạn này là nền tảng để xây dựng tài liệu. Để hỗ trợ người viết 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 có liên quan và mẹo về việc xây dựng cấu trúc cho thông tin này bằng các mẫu.

Sau đó là giai đoạn viết. Người viết được cung cấp các ví dụ về tác phẩm hay để tự động đặt tiêu chuẩn cao. Hơn nữa, danh sách kiểm tra được tạo với một bộ tiêu chí cơ bản mà mọi tài liệu đều phải tuân theo, điều này sẽ hỗ trợ người viết trong việc xem xét tài liệu của mình trước khi xuất bản.

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

Cuối cùng, tài liệu giúp bạn 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 kiểm thử và cải thiện.

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

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

“Một trong những cách khó nhất để học những thứ 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 phần mềm thủ công của bạn sử dụng sai phiên bản phần mềm. 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 hành động khi trình đơn và từ ngữ trong ứng dụng thay đổi vì chúng ta thiếu tất cả các gợi ý thường dùng.

Có lẽ cách tốt nhất để học là khi có một chuyên gia ngồi ngay bên cạnh bạn. Các bản ghi màn hình được đặt giữa các hình ảnh tĩnh và có một chuyên gia trợ giúp. Chúng ta có được một bản minh hoạ trực quan, chuyển độ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 mỗi giờ mỗi ngày.

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

Trong đoạn mã trên của ""Sổ tay ghi lại chuyển động trên 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 việc ghi lại chuyển động trên màn hình. Khoá học này có thể đặc biệt hữu ích đối với các hướng dẫn thiết lập môi trường phát triển MediaWiki, viết tiện ích, sử dụng Gerrit, v.v.

Tương tự như mẫu tài liệu, việc có một mẫu chuẩn cho video ghi lại chuyển động trên màn hình giúp làm tăng tính thống nhất, từ đó nâng cao trải nghiệm của người xem. Chương trình này cũng cung cấp khung làm việc để bắt đầu cho những nhà quay phim tiềm năng. Do đó, chúng tôi phát triển 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. Tài liệu này bao gồm những gợi ý về mức độ chuyên sâu của các khái niệm cần được đề cập và một số ý tưởng về video ghi lại màn hình cho MediaWiki.

Cách tốt nhất để thử nghiệm mẫu trên và chuẩn bị cho mục tiêu kéo dài là tạo một bản ghi màn hình bằng các công cụ và mẫu. Do đó, chúng tôi tạo bản ghi màn hình "Giới thiệu về Trình tạo pha" trình bày các thông tin cơ bản về việc sử dụng Trình tạo pha. Quá trình này cũng sẽ làm nổi bật những lĩnh vực cần thảo luận.

Cuối cùng, nguồn tài liệu tham khảo trung tâm 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

Thời gian gắn kết cộng đồng (1/8 – 1/9)

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

  • Thảo luận về:

    • Tần suất đánh giá việc cần làm.
    • 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 hai tuần một lần và hằng ngày.

  • Tạo các nhiệm vụ và nhiệm vụ phụ cần thiết trên Phabricator.

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

Tuần 1 (2 – 8/9)

  • Cải thiện Tài liệu/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 ví dụ về những trang đáng tin cậy và cải thiện khả năng hiển thị của các trang được 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 – 15/9)

  • Sắp xếp mức độ ưu tiên về tài liệu kỹ thuật:

    • Đánh giá bảng tài liệu; tìm ví dụ về nội dung mô tả và mức độ ưu tiên phù hợp cho nhiệm vụ.
    • Hãy nghiên cứu xu hướng và ghi lại những khó khăn thường gặp.
    • Dùng thông tin và ví dụ để ghi lại các tiêu chuẩn về mức độ ưu tiên.

Tuần 3 (16-22/9)

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

    • Danh sách kiểm tra giúp xem xét tài liệu kỹ thuật trước khi xuất bản.
    • Những cách thu thập nội dung hiệu quả cho các thể loại tài liệu khác nhau.

Tuần 4 (23-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 các mẫu và nội dung đề xuất của tài liệu 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, hướng dẫn bắt đầu nhanh, tệp README, ghi chú phát hành và hướng dẫn.

  • Thêm thông tin chỉ đường để cải thiện sự trưởng thành của hoạt động giao tiếp 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 để giới thiệu cộng tác viên mới:

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

  • Xây dựng trung tâm cho tác giả kỹ thuật

    • Tạo trang đích chứa đườ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 đến trang mới và trang hiện có để dễ dàng di chuyển giữa các trang.

Tuần 6 (ngày 7 – 13 tháng 10)

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

    • Một hướng dẫn nhanh về cách tạo bản ghi màn hình chung trỏ đến Dự án Screencast.
    • Mẫu: 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 ghi màn hình cho MediaWiki.

Tuần 7 (từ ngày 14 đến 20 tháng 10)

  • Làm video ""Giới thiệu về Phabricator""

    • Sử dụng mẫu (đã tạo trong tuần trước) để soạn thảo 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 (từ ngày 21 đến 27 tháng 10)

  • Xuất bản video "Giới thiệu về Trình điều phối":

    • 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/10 – 3/11)

  • Cách cải thiện tài liệu của dự án Screencast:

    • Xem xét cấu trúc này và thảo luận về nhu cầu thay đổi.
    • Xem 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-10/11)

  • Tiếp tục cải thiện tài liệu của dự án Screencast:

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

Tuần 11 (11-17/11)

  • Hoàn thành tài liệu của dự án Screencast:

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

Tuần 12 (18-24/11)

  • Xử lý mọi việc đang chờ xử lý.

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

    • Tham khảo các báo cáo hai tuần một lần/hằng ngày để thu thập những 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 nháp dựa trên ý kiến phản hồi của người cố vấn.

Tuần 13 (25-29/11)

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

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

Thông tin cập nhật về tiến độ hằng ngày sẽ được thông báo cho cố vấn của tôi qua Zulip. Cộng đồng Wikimedia có thể theo dõi tiến độ của tôi thông qua Phabricator hoặc các báo cáo dự án hai tuần một lần.

7. Các 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 dòng thời gian của Phần Tài liệu. Do đó, cam kết của tôi bao gồm cả các kỳ thi đại học.

Kỳ thi nội bộ đầu tiên: ngày 18 đến 24 tháng 8

Kỳ thi nội bộ lần 2: từ ngày 29/9 đến ngày 6/10.

Kỳ thi cuối học kỳ: ngày 11 đến ngày 30 tháng 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 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ý những cam kết này, tiến trình dự kiến sẽ bao gồm các nhiệm vụ ít trọng trọng hơn vào các tuần tương ứng. Tôi dự định sẽ hoàn thành không quá 20 tín chỉ chính trong học kỳ mùa thu để có đủ thời gian soạ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ỳ)