Dự án VLC

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ở:
VLC
Tác giả kỹ thuật:
Abhishek Pratap Singh
Tên dự án:
Tiếp tục hiện đại hoá tài liệu người dùng VLC
Thời lượng dự án:
Thời hạn tiêu chuẩn (3 tháng)

Mô tả dự án

TRẠNG THÁI HIỆN TẠI CỦA TÀI LIỆU

Tài liệu hướng dẫn người dùng VLC đang trong quá trình hiện đại hoá và cập nhật. Chúng tôi đang chuyển đổi từ tài liệu cũ dựa trên wiki[1] sang tài liệu người dùng hiện đại được tạo bằng sphinx[2] và được lưu trữ trên ReadTheDocs.

ĐỐI TƯỢNG MỤC TIÊU

Đối tượng mục tiêu vừa là những người dùng tò mò muốn khám phá các tính năng của trình phát nội dung đa phương tiện VLC ngoài một trình phát nội dung đa phương tiện thông thường. Ở một mức độ nào đó, trình phát này sẽ giúp nhà phát triển và trở thành một tài liệu hướng dẫn tham khảo dễ sử dụng. Do đó, tôi dự định đưa vào cả hướng dẫn dựa trên GUI (cùng với hình ảnh nếu có liên quan) và phương thức dựa trên CLI (cùng với đoạn mã) để người dùng cuối có thể tự do lựa chọn.

Tôi tin rằng ngôn ngữ của tài liệu (đặc biệt là phần GUI) nên được chỉnh sửa vừa đủ để những người chỉ tiếp xúc với máy tính đang hoạt động trên danh nghĩa có thể hiểu và thực hiện hướng dẫn này. Mặt khác, tài liệu không được quá dài hoặc giải thích quá chi tiết (đặc biệt là phần CLI) khiến lập trình viên mất hứng thú.

Bạn có thể đạt được sự cân bằng phù hợp bằng cách đề cập đến các điều kiện tiên quyết ở đầu trang hoặc giữ lại các phần không bắt buộc mà những người đã nắm rõ có thể bỏ qua.

Đối tượng mục tiêu để xây dựng bản dịch là các nhà phát triển/người dùng VLC nắm rõ tiếng Anh và ngôn ngữ mà họ sẽ dịch sang.

CÔNG CỤ

Tài liệu mới đang được Sphinx xây dựng và được lưu trữ trên ReadTheDocs, đồng thời hệ thống quản lý phiên bản được triển khai trong GitLab. Tôi đã có một số kinh nghiệm sử dụng Git và GitHub, điều này giúp tôi làm quen với GitLab, mặc dù có một số tính năng khác cần thời gian để tìm hiểu.

Đối với Sphinx, tôi đã đọc về nó khi một người đam mê nguồn mở khác nhận xét có bao nhiêu tổ chức đang sử dụng nó để xây dựng tài liệu của họ (với ví dụ đáng chú ý là Binder, sử dụng Sphinx để xây dựng Hướng dẫn sử dụng và tài liệu API [4]).

Tôi đã quen thuộc một chút với ReadTheDocs. Đây là một công cụ phù hợp để tạo phiên bản và lưu trữ tài liệu kỹ thuật. Do đó, tôi có thể tạo tài liệu VLC mà không gặp nhiều vấn đề và đã quen thuộc với định dạng Văn bản được tái cấu trúc.

Đối với các bản dịch, VLC sử dụng adb để tạo các tệp .po nhằm triển khai i18n và l10n. Hiện tại, tôi đang làm quen với quy trình làm việc của Babel và cách tạo tệp .mo bằng Sphinx.

Tôi dự định sử dụng khoảng thời gian gắn bó này để làm quen hơn với những chi tiết phức tạp của các công cụ nêu trên.

SẢN PHẨM VÀ LỊCH TRÌNH HÀNG TUẦN

Trong dự án năm 2019, các phần Cài đặt, Giao diện, Âm thanh, Video, Phát, v.v. (hầu hết các chức năng cơ bản) đã được đề cập. Do đó, đối với dự án năm 2020, tôi muốn cập nhật và xử lý mục sử dụng nâng cao trong tài liệu về Người dùng.

PHÁT TRIỂN 1 [Tuần 1-2]: Cập nhật Tài liệu về Chuyển mã, như đã đề cập trong #7 [5].

  • Chuyển mã
  • Chuyển mã nhiều video
  • Thêm biểu trưng
  • Hợp nhất các video với nhau
  • Trích xuất âm thanh và Trích xuất âm thanh từ tệp
  • Sao chép DVD

SẢN PHẨM 2 [Tuần 3-4]: Cập nhật cách sử dụng VLC làm trình bổ trợ web[6], trong khi kiểm thử trong Firefox 77, Chrome 83 và Edge 83.

  • Tạo trang web bằng video
  • Nhúng thuộc tính thẻ
  • Nội dung mô tả API JavaScript

SẢN PHẨM 3 [Tuần 5]: Kiểm thử các lệnh trên Giao diện dòng lệnh[7] và cập nhật cho phù hợp.

  • Lượt phát trực tuyến
  • Lựa chọn mô-đun
  • Các lựa chọn theo mặt hàng cụ thể
  • Bộ lọc

Tuần 6: Tuần đệm cho 3 sản phẩm nói trên.

GIAO DIỆN 4 [Tuần 7-8]: Chuẩn bị cho việc dịch thuật. Ngoài việc cập nhật, tôi sẽ chuẩn bị cho việc dịch sang các ngôn ngữ khác. Điều này rất quan trọng vì sau khi dịch, người dùng không biết tiếng Anh sẽ có thể đọc tài liệu (và ngoài ra, VLC sẽ tiến gần hơn một bước đến việc thống trị thế giới[8]).

Như đã đề cập trong phần Công cụ của đề xuất, VLC hiện sử dụng Babel để tạo tệp .po cho bản dịch. Tôi sẽ ghi lại quy trình để người dùng/người tình nguyện:

  • Tải xuống và tạo tài liệu cơ sở trên máy.
  • Sử dụng Babel để tạo các tệp bắt buộc.
  • Nhập Bản dịch cho các chuỗi.
  • Tạo tài liệu đã dịch bằng Sphinx.
  • Gửi các thay đổi.

GIAO DIỆN 5 [Tuần 9-10]: Chuẩn bị tài liệu học phần. Như đã thảo luận với các cố vấn, tôi dự định chuẩn bị tài liệu về các mô-đun theo hai phần.

Phần 1: Tạo các tệp gần với các mô-đun thông qua một tập lệnh tìm kiếm các tuỳ chọn hợp lệ từ cơ sở mã và trích xuất cách sử dụng một dòng (và giá trị mặc định) của các tuỳ chọn đó từ các trang wiki tương ứng. Đây sẽ là bản nháp cơ bản.

Phần – II: Xây dựng một cấu trúc dành riêng cho một nền tảng liên kết tất cả mô-đun+trình bổ trợ+tuỳ chọn cho một nền tảng cụ thể (dành cho Windows và nếu có thì cũng dành cho phớt).

Việc tạo tệp gần các mô-đun sẽ đảm bảo tài liệu nằm gần mã nguồn. Theo cách tiếp cận từ dưới lên, Tài liệu Mô-đun chính sẽ được xây dựng bằng cách kết hợp các tệp đã tạo trong Phần I và sử dụng cấu trúc trong Phần – II làm tài liệu tham khảo.

Các tệp được tạo thông qua tính năng tự động hoá sẽ cần được xem xét, nhưng ưu tiên hàng đầu là tạo một khung chức năng. Sau khi đạt được mục tiêu đó và tuỳ theo thời gian có thể, tôi sẽ xem xét các tệp để xác minh các lựa chọn. Khung này đang được ưu tiên vì sau khi có sẵn, các nhà phát triển và người bảo trì cũng có thể bắt đầu đóng góp bằng cách thêm các trường hợp sử dụng có liên quan.

SẢN PHẨM BỔNG [Tuần 11]: Chuẩn bị cho bản phát hành 4.0. Trong trường hợp dự án vẫn diễn ra đúng tiến trình, tôi muốn đề xuất một sản phẩm bổ sung. Như đã thảo luận với các cố vấn, việc chuẩn bị cho bản phát hành 4.0 đồng nghĩa với việc bạn phải có tài liệu ổn định và gần như hoàn chỉnh cho phiên bản 3.0.

Do đó, tôi sẽ xem lại tài liệu đã hoàn tất của các phần sau để xác minh và cập nhật các phương thức được đề cập:

  • Cách sử dụng cơ bản: Nội dung nghe nhìn, Phát, Âm thanh, Video, Phụ đề, Phím tắt, Bản ghi, Cài đặt, Mẹo và thủ thuật.
  • Cách sử dụng nâng cao: Trình phát, Giao diện, Chuyển mã, Truyền trực tuyến, Trường hợp bất thường.
  • Tiện ích bổ sung: Tiện ích, Giao diện.

Tuần 12: Tuần dự phòng cho 3 sản phẩm trên + Báo cáo cuối cùng.

TẠI SAO TÔI LÀ NGƯỜI PHÙ HỢP CHO DỰ ÁN NÀY?

Là một người đam mê công nghệ, tôi có kinh nghiệm sử dụng/kiểm thử phần mềm và đôi khi cố gắng tìm hiểu cơ sở mã của các phần mềm đó. Trên thực tế, việc cố gắng tìm hiểu cơ sở mã của một tổ chức nguồn mở là lần đầu tiên tôi thực sự nhận ra tầm quan trọng của tài liệu. Ngoài ra, là một người đam mê âm nhạc, tôi có nhiều kinh nghiệm điều chỉnh VLC :)

Ngoài ra, tôi còn là nhà nghiên cứu và nhà văn trong cả đời. Trừ phi tôi viết ra, tôi sẽ không bao giờ thực sự hiểu được điều gì đó. Thói quen này đã giúp tôi trở thành một người ghi chú và ghi chép tài liệu hiệu quả.

Sự kết hợp của hai thói quen này là lý do khiến tôi phù hợp với việc viết tài liệu kỹ thuật. Tôi có thể tìm hiểu các khía cạnh kỹ thuật cùng với việc ghi lại những phát hiện/quy trình của mình theo cách mà người dùng hiểu được.

Đường liên kết: [1] https://wiki.videolan.org/Documentation:User_Guide/ [2] https://vlc-user-documentation.readthedocs.io/en/latest/index.html [3] https://docs.blender.org/manual/en/latest/ [4] https://docs.blender.org/api/current/index.html [5] https://code.videolan.org/docs/vlc-user/-/issues/7 [6] https://wiki.videolan.org/Documentation:WebPlugin/ [7] https://wiki.videolan.org/Documentation:Command_line/ [8] https://trac.videolan.org/vlc/ticket/35