Dự án VideoLAN

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 tài liệu của Google.

Tóm tắt dự án

Tổ chức nguồn mở:
VideoLAN
Người viết nội dung kỹ thuật:
Edidiong Anny Asikpo
Tên dự án:
Hiện đại hoá (viết lại) tài liệu người dùng VLC
Độ dài dự án:
Thời hạn tiêu chuẩn (3 tháng)

Mô tả dự án

ABSTRACT

Tài liệu người dùng được thiết kế để hỗ trợ người dùng cuối sử dụng một sản phẩm hoặc dịch vụ. Tài liệu người dùng tốt rất quan trọng vì nó cung cấp cho người dùng một phương tiện để tìm hiểu cách sử dụng phần mềm, các tính năng, mẹo và thủ thuật của phần mềm cũng như giải quyết các vấn đề thường gặp khi sử dụng phần mềm. Việc này cũng giúp giảm chi phí hỗ trợ và là một phần của bản sắc doanh nghiệp của sản phẩm: tài liệu người dùng tốt là dấu hiệu cho thấy sản phẩm và nhóm nhà phát triển đang hoạt động hiệu quả.

Nếu không có tài liệu người dùng phù hợp, người dùng có thể không biết cách thực hiện những việc trên một cách hiệu quả. Tài liệu người dùng có thể đóng một vai trò quan trọng trong việc đảm bảo sự thành công của sản phẩm bởi vì giao tiếp hiệu quả là và sẽ luôn là trọng tâm của bất kỳ doanh nghiệp hoặc sản phẩm nào và một tài liệu tuyệt vời chỉ cần sự giao tiếp đó và đặt nó vào một khuôn khổ dễ quản lý mà ai cũng có thể truy cập để thành công.

Tại thời điểm viết bài này, tài liệu người dùng VLC đã được truy cập 4.634.065 lần và trình phát nội dung đa phương tiện VLC được tải xuống khoảng 23 triệu lần mỗi tháng từ trang web chính. Điều này cho thấy rằng nhiều người trên khắp thế giới sử dụng Trình phát nội dung đa phương tiện VLC và có thể muốn đọc tài liệu người dùng để được hướng dẫn cách sử dụng trình phát nội dung đa phương tiện này. Tuy nhiên, tài liệu hướng dẫn người dùng về trình phát nội dung đa phương tiện VLC hiện đã lỗi thời và chưa hoàn chỉnh (lần sửa đổi gần đây nhất là vào ngày 28 tháng 10 năm 2015). Cộng đồng VideoLAN muốn sử dụng dự án này để cải thiện tài liệu hướng dẫn người dùng nhằm giúp người dùng cuối có trải nghiệm liền mạch khi sử dụng trình phát nội dung đa phương tiện VLC.

TRẠNG THÁI HIỆN TẠI

Hiện tại, tài liệu dành cho người dùng có trên trang wiki. Trang này đã lỗi thời, chưa hoàn chỉnh, khó điều hướng hoặc tìm thông tin, không bao gồm thông tin về phiên bản trình phát nội dung nghe nhìn hiện tại và chỉ có thể được dịch sang tiếng Đức, gây ra sự bất tiện lớn cho những người không đọc được tiếng Anh.

TẠI SAO TÀI LIỆU ĐỀ XUẤT CHO NGƯỜI DÙNG CỦA TÔI LÀ MỘT BƯỚC CẢI TIẾN SO VỚI TÀI LIỆU HIỆN TẠI?

Tài liệu người dùng được đề xuất sẽ được sắp xếp để cải thiện và đảm bảo hiệu quả, tính nhất quán và sự an tâm cho người dùng cuối. Tài liệu này sẽ chứa hướng dẫn bằng văn bản và hình ảnh liên quan, bao gồm hướng dẫn và giải thích về cách sử dụng từng tính năng của trình phát đa phương tiện VLC. Tài liệu này mới nhất, dễ thao tác, dễ hiểu và có thể dịch bằng ít nhất năm ngôn ngữ chính.

Người cố vấn: Jean-Baptiste, Alex, Simon

PHÂN TÍCH

Jean-Baptiste và tôi đã trò chuyện về môi trường mới mà tài liệu người dùng hiện tại sẽ được di chuyển sang để cải thiện và anh ấy đã chia sẻ hai đường liên kết cho thấy kho lưu trữ Gitlab của tệp nguồn được viết bằng Sphinx và tài liệu chính được lưu trữ trên Read the Tài liệu và anh ấy nói rằng họ mong đợi tài liệu mới cũng giống như tài liệu đó. Tôi đã nghiên cứu rất nhiều về các công cụ này để hiểu rõ hơn về cách hoạt động của chúng.

Tượng Nhân sư

Sphinx là một giải pháp mạnh mẽ và hoàn thiện dành cho tài liệu phần mềm. Phiên bản này bao gồm một số tính năng mà nhà văn mong đợi, chẳng hạn như phát hành từ một nguồn duy nhất, sử dụng lại nội dung thông qua các tệp bao gồm, tệp bao gồm có điều kiện dựa trên loại nội dung và thẻ, nhiều giao diện HTML hoàn chỉnh mang lại trải nghiệm người dùng tuyệt vời trên thiết bị di động và máy tính, tham chiếu trên các trang, tài liệu và dự án, hỗ trợ mục lục và từ điển cũng như hỗ trợ quốc tế hoá. Công cụ này cũng sử dụng reStructuredText làm ngôn ngữ đánh dấu và nhiều điểm mạnh của công cụ này đến từ sức mạnh và tính đơn giản của reStructuredText cũng như khả năng dịch tài liệu.

Đọc Tài liệu

Đọc Tài liệu đơn giản hoá tài liệu về phần mềm bằng cách tự động xây dựng, tạo phiên bản và lưu trữ tài liệu cho bạn. Tính năng này sẽ không bao giờ bị đồng bộ hoá; nghĩa là bất cứ khi nào bạn đẩy mã vào hệ thống quản lý phiên bản yêu thích của mình, cho dù đó là Git, Mercurial, Marketplace hay Subversion, tính năng Đọc tài liệu sẽ tự động tạo tài liệu để mã và tài liệu của bạn luôn cập nhật. Tài liệu có nhiều phiên bản; Read the Docs có thể lưu trữ và tạo nhiều phiên bản tài liệu, vì vậy, việc có phiên bản tài liệu 1.0 và phiên bản tài liệu 2.0 cũng dễ dàng như việc có một nhánh hoặc thẻ riêng biệt trong hệ thống quản lý phiên bản. Read the Docs là một trang web nguồn mở và miễn phí,lưu trữ tài liệu cho gần 100.000 dự án nguồn mở lớn và nhỏ bằng hầu hết ngôn ngữ của con người và máy tính.

KẾT QUẢ

Sphinx là một công cụ cực kỳ mạnh mẽ và Read the Docs được xây dựng dựa trên công cụ này để cung cấp dịch vụ lưu trữ cho tài liệu Sphinx, giúp tài liệu của bạn luôn được cập nhật trên các phiên bản. Đây là một bộ công cụ tuyệt vời mà các nhà phát triển và nhà văn kỹ thuật có thể sử dụng để tạo tài liệu người dùng phù hợp nhất với người dùng cuối.

Sphinx hỗ trợ dịch tài liệu sang nhiều ngôn ngữ. Thư viện này hỗ trợ tính năng kiểm soát phiên bản sẽ được dùng để quản lý tài liệu. Không giống như wiki hiện tại, nơi bất kỳ ai cũng có thể chỉnh sửa và không thêm thông tin chính xác, hệ thống quản lý phiên bản này sẽ đảm bảo rằng tất cả thay đổi đều được xem xét trước khi được hợp nhất vào kho lưu trữ chính. Việc kiểm soát phiên bản cũng sẽ làm cho tài liệu tăng đóng góp nguồn mở cho dự án vì mọi người có thể tạo ra sự cố, mở yêu cầu kéo, v.v. Sphinx và đọc Tài liệu được sử dụng bởi danh sách các cộng đồng và tuyệt vời khác như; ASP.NET, Kernel, Julia, Jupyter, PHPMyAdmin, Write the Tài liệu, v.v. và đó là một công cụ tuyệt vời để sử dụng cho tài liệu người dùng VLC mới.

Tôi không chỉ đọc về các công cụ này, tôi còn tạo một mẫu cơ bản. Đây là đường liên kết: https://gitlab.com/Didicodes/demo-vlc-user-documentation đến kho lưu trữ Gitlab của tôi, trong khi bạn có thể tìm thấy phiên bản được lưu trữ trên readthedocs tại đây: [https://vlc-user-documentation-demo.readthedocs.io/en/latest/](https://vlc-user-documentation-demo.readthedocs.io/en/latest/.

CẤU TRÚC CỦA TÀI LIỆU ĐỀ XUẤT

Tôi đã tạo một cấu trúc cho Tài liệu người dùng VLC có thể tìm thấy tại đây; https://docs.google.com/document/d/1Sy2V2IADoCyfnGBK70v8mkjiWK2tH-oWdUlDxAfQAYA/edit?usp=sharing. Trước khi bắt đầu triển khai cấu trúc mới này, bạn phải được các cố vấn phê duyệt. Điều này có nghĩa là cấu trúc có thể thay đổi sau khi các cố vấn xem xét.

MỤC TIÊU DỰ ÁN

  • Điều chỉnh lại cấu trúc tài liệu.
  • Cập nhật tài liệu cho phù hợp với các phiên bản VLC hiện đại.
  • Di chuyển tài liệu người dùng sang Gitlab bằng Sphinx và ReadtheDocs.
  • Xoá hình ảnh và thông tin lỗi thời.
  • Viết lại tài liệu người dùng để dễ hiểu hơn.
  • Thiết lập để dịch bằng tính năng Quốc tế hoá Sphinx.
  • Xây dựng tài liệu do cộng đồng điều hướng để người dùng có thể báo cáo hoặc giải quyết mọi vấn đề gặp phải trong khi đọc tài liệu.

TẠI SAO CÓ DỰ ÁN NÀY?

Tôi luôn tin rằng việc viết mã, giải quyết vấn đề và xây dựng phần mềm sẽ phát huy tối đa tiềm năng của mình khi bạn cũng có thể khiến người khác hiểu rõ về nó thông qua việc viết mã. Cá nhân tôi luôn bị cuốn hút bởi những nỗ lực mà cộng đồng VideoLAN đã thực hiện trong việc tạo ra các giải pháp phần mềm miễn phí cho nội dung đa phương tiện. Khi lớn lên, trình phát đa phương tiện VLC luôn là phần mềm tôi sử dụng khi nghe nhạc hoặc xem phim vì trình phát này rất to và bao gồm nhiều tính năng. Tôi rất vinh dự được làm việc với cộng đồng đã góp phần tạo nên tuổi thơ tuyệt vời cho tôi.

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

Tôi tin rằng mình là người phù hợp cho dự án này vì:

  • Tôi có kinh nghiệm cải thiện tài liệu của các tổ chức và có thể sử dụng bất kỳ hệ thống quản lý phiên bản nào, vì vậy, việc thực hiện các lệnh trên Gitab sẽ không thành vấn đề. Hơn nữa, tôi được thúc đẩy bởi việc làm việc trên các dự án tạo ra giá trị cho mọi người.
  • Tôi tin rằng nếu muốn người khác làm việc theo cách hiệu quả nhất có thể, bạn phải ghi lại việc đó. Bằng cách ghi lại quy trình, bạn đảm bảo tính hiệu quả, tính nhất quán và sự an tâm cho mọi người liên quan.
  • Tôi biết nhu cầu của người dùng VLC vì tôi cũng là một trong số đó. Điều này cho phép viết tài liệu theo cách mà mọi người dùng khác trên toàn cầu đều có thể hiểu ngay từ lần đầu.