Dự án VLC

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ở:
VLC
Người viết nội dung kỹ thuật:
Abhishek Pratap Singh
Tên dự án:
Tiếp tục hiện đại hoá tài liệu dành cho người dùng VLC
Thời lượng dự án:
Thời gian 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

Chúng tôi đang hiện đại hoá và cập nhật Tài liệu về người dùng VLC. Quá trình chuyển đổi đang trong quá trình chuyển từ tài liệu cũ hơn dựa trên wiki[1] sang tài liệu dành cho người dùng hiện đại được xây dựng của nhân sư [2] được lưu trữ trên ReadTheDocs.

NHẮM MỤC TIÊU KHÁN GIẢ

Đối tượng mục tiêu bao gồm cả những người dùng hiếu kỳ và 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. Trong một phạm vi nào đó, trình phát nội dung đa phương tiện này cũng sẽ giúp nhà phát triển bằng cách trở thành một hướng dẫn tham khảo đơn giản. 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ó) và các phương thức dựa trên CLI (cùng với đoạn mã) để người dùng cuối có quyền 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) phải được ngắn gọn đến mức một người thường xuyên tiếp xúc với máy tính có thể hiểu và triển khai hướng dẫn này. Mặt khác, không nên quá dài hoặc không giải thích (đặc biệt là phần CLI) mà các lập trình viên mất hứng thú.

Để tạo sự cân bằng phù hợp, hãy đề 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à người dùng thành thạo có thể bỏ qua.

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

CÔNG CỤ

Tài liệu mới này do Sphinx xây dựng và 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 trước đây khi sử dụng Git và GitHub, điều này đã giúp tôi hiểu rõ GitLab, mặc dù có một số tính năng khác nhau nhất định mất một thời gian để tìm hiểu.

Đối với Sphinx, tôi đã đọc về nó khi một người đam mê mã nguồn mở 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ú ý về Sphinx, sử dụng Sphinx để xây dựng Hướng dẫn sử dụng và tài liệu API [4]).

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

Đối với bản dịch, VLC đang sử dụng Bumblebee để tạo 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 Bumblebee và cách tạo tệp .mo bằng Sphinx.

Tôi dự định sử dụng thời gian liên kết để hiểu rõ hơn về những điểm phức tạp của các công cụ nêu trên.

HÀNG TUẦN

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

1 [Tuần1-2]: Cập nhật tài liệu 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
  • Trích xuất DVD

CÓ THỂ DELIVERABLE 2 [Tuần 3-4]: Cập nhật bằng cách sử dụng VLC làm trình bổ trợ web [6], trong khi thử nghiệm trong Firefox 77, Chrome 83 và Edge 83.

  • Tạo trang web có video
  • Nhúng thuộc tính thẻ
  • Mô tả API JavaScript

CÓ THỂ DÙNG 3 [Tuần 5]: Kiểm tra các lệnh 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ục cụ thể
  • Bộ lọc

Tuần 6: Tuần lễ đệm cho ba sản phẩm trên.

DELIVERABLE 4 [Tuần 7-8]: Chuẩn bị cho bản dịch. Ngoài việc cập nhật, tôi sẽ chuẩn bị bản dịch sang các ngôn ngữ khác. Điều này rất quan trọng vì sau khi dịch, những người dùng không có nền tảng tiếng Anh vẫn có thể đọc được tài liệu (và chú ý thêm, VLC sẽ là một bước gần hơn để đạt được sự 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 Bumblebee để tạo tệp .po cho bản dịch. Tôi sẽ ghi lại quy trình cho người dùng/tình nguyện viên để:

  • Tải xuống và tạo bản dựng tài liệu cơ sở cục bộ.
  • Sử dụng Jetpack để tạo các tệp cần thiết.
  • Nhập Bản dịch cho chuỗi.
  • Xây dựng tài liệu đã được dịch bằng Sphinx.
  • Áp dụng các thay đổi.

5 [Tuần 9-10]: Chuẩn bị cho tài liệu về các mô-đun. Như đã trao đổi với các người cố vấn, tôi dự định chuẩn bị tài liệu về học phần gồm hai phần.

Phần - I: Tạo tệp gần các mô-đun thông qua tập lệnh tì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à các giá trị mặc định) của chúng 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 cấu trúc dành riêng cho 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ể (Windows và nếu thời gian cho phép, cũng đối với Fedora).

Việc tạo tệp gần các mô-đun sẽ đảm bảo rằng tài liệu gần với mã nguồn. Sử dụng phương pháp từ dưới lên trên, Tài liệu chính về mô-đun sẽ được xây dựng bằng cách kết hợp các tệp đã trình bày 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.

Những tệp được tạo thông qua hệ thố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. Khi đã đạt được điều đó, và theo thời gian hiện có, 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 ngay khi ra mắt, các nhà phát triển và nhà 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.

NHẬN THƯỞNG CÓ THỂ DÙNG [Tuần 11]: Chuẩn bị cho bản phát hành 4.0. Trong trường hợp dự án đúng tiến độ, tôi xin đề xuất một phần thưởng có thể phân phối. Như đã trao đổi với các chuyên viên cố vấn, việc chuẩn bị cho bản phát hành 4.0 ngụ ý việc có một 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 xét tài liệu đã hoàn thành 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 nóng, 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ã, Phát trực tuyến, Các trường hợp bất thường.
  • Tiện ích bổ sung: Tiện ích, Trang phục.

Tuần 12: Tuần lễ đệm cho ba 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 hiểu cơ sở mã của họ. Trên thực tế, lần đầu tiên tôi thực sự nhận ra tầm quan trọng của tài liệu là lần đầu tiên tôi thực sự hiểu được tầm quan trọng của tài liệu khi cố gắng nắm được cơ sở mã của một tổ chức nguồn mở. Hơn nữa, là một người đam mê âm nhạc, tôi có rất nhiều kinh nghiệm điều chỉnh VLC :)

Ngoài ra, cả đời tôi cũng là một nhà nghiên cứu và nhà văn. Nếu không viết ra được điều gì đó thì tôi hoàn toàn không hiểu được. Và thói quen này đã biến tôi thành một người ghi chú và ghi chép hiệu quả.

Sự giao thoa của hai thói quen này là điều khiến tôi phù hợp với 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 các 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/Tài liệu:User_Guide/videolan.org/Tài liệu:https://vlc-user-document.readthedocs.io/en/latest/index.html [3] https://docs.bfragment.org/manual/en/latest/ [4] https://docs.butter.org/api/current/index.html/lc.org/api/.