Trang này được dịch bởi Cloud Translation API.

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 Google Tài liệu.

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á (ghi lại) tài liệu 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

TÓM TẮT

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 hướng dẫn người dùng tốt là tài liệu rất quan trọng vì nó mang đến một không gian để người dùng tìm hiểu cách sử dụng phần mềm, các tính năng, mẹo, thủ thuật và cũng như giải quyết các vấn đề thường gặp khi sử dụng phần mềm. Điều này cũng giúp giảm chi phí hỗ trợ và là một phần tạo nên bản sắc doanh nghiệp của sản phẩm: tài liệu của người dùng hợp lệ là dấu hiệu cho thấy tình trạng của sản phẩm, chính là của nhóm nhà phát triển.

Nếu không có tài liệu hướng dẫn cụ thể về người dùng, 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 về người dùng có thể đóng vai trò then chốt trong việc đảm bảo thành công của sản phẩm vì khả năng giao tiếp tốt sẽ luôn là yếu tố trọng tâm của mọi doanh nghiệp hoặc sản phẩm. Ngoài ra, một tài liệu tuyệt vời chỉ bao gồm thông tin liên lạc đó và đặt chúng trong một khung làm việc dễ quản lý mà mọi người đều 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 về người dùng VLC đã được truy cập 4.634.065 lần và trình phát đ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ất nhiều người trên toàn thế giới sử dụng VLC Media Player và có thể muốn đọc tài liệu người dùng của nó để được hướng dẫn về cách sử dụng trình phát đa phương tiện. Tuy nhiên, tài liệu dành cho người dùng của trình phát đa phương tiện VLC hiện đã lỗi thời và chưa đầy đủ (thông tin này được sửa đổi lần gần đây nhất vào ngày 28 tháng 10 năm 2015). Do đó, cộng đồng VideoLAN muốn sử dụng dự án này để cải thiện tài liệu người dùng nhằm tạo điều kiện cho người dùng cuối có trải nghiệm liền mạch khi sử dụng trình phát đa phương tiện VLC.

TIỂU BANG HIỆN TẠI

Hiện tại, tài liệu người dùng có sẵn trên trang wiki. Ứng dụng này đã lỗi thời, không đầy đủ, khó điều hướng hoặc tìm thông tin, không cung cấp thông tin về phiên bản hiện tại của trình phát nội dung đa phương tiện và chỉ có thể dịch sang tiếng Đức. Điều này sẽ gây trở ngại lớn cho những người không thể đọc tiếng Anh.

TẠI SAO TÔI ĐƯỢC ĐỀ XUẤT TÀI LIỆU CHO NGƯỜI DÙNG TẠO NÊN CẢI TIẾN SO VỚI BẢN NHẠC HIỆN TẠI?

Tài liệu dành cho người dùng mà bạn đề xuất sẽ được cấu trúc để cải thiện và đảm bảo tính 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 có hướng dẫn bằng văn bản và hình ảnh liên quan, hướng dẫn và giải thích cách sử dụng từng tính năng của trình phát đa phương tiện VLC, cập nhật, dễ sử dụng, dễ hiểu và dịch được bằng ít nhất 5 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 tiế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ọ hy vọng tài liệu mới sẽ tương tự như đó. 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 cho tài liệu phần mềm. API này có một số tính năng mà người viết mong đợi, chẳng hạn như xuất bản một nguồn, sử dụng lại nội dung, bao gồm, bao gồm có điều kiện dựa trên loại và thẻ nội dung, nhiều chủ đề HTML hoàn thiện 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 để bàn, tham chiếu qua các trang, tài liệu và dự án.Hỗ trợ Chỉ mục và Bảng chú giải thuật ngữ cũng như hỗ trợ quốc tế hoá. Định dạng này cũng sử dụng reStructureText làm ngôn ngữ đánh dấu. Nhiều điểm mạnh của reStructureText đến từ sức mạnh và tính đơn giản của reStructureText cũng như khả năng dịch tài liệu.

Đọc Tài liệu

Đọc Tài liệu giúp đơn giản hoá tài liệu phần mềm bằng cách tự động hoá quy trình xây dựng, tạo phiên bản và lưu trữ tài liệu cho bạn. Tài liệu này không bao giờ bị gián đoạn; 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 mà mình yêu thích, dù đó là Git, Mercurial, Marketplace hay Subversion, thì tính năng Đọc tài liệu sẽ tự động tạo tài liệu của bạn để mã và tài liệu của bạn luôn được cập nhật. Ứng dụng này có nhiều phiên bản; Đọc Tài liệu có thể lưu trữ và xây dựng nhiều phiên bản tài liệu của bạn, vì vậy, việc có phiên bản 1.0 của tài liệu và phiên bản 2.0 của tài liệu dễ dàng như việc có nhánh hoặc thẻ riêng biệt trong hệ thống quản lý phiên bản của bạn. Đọc Tài liệu là nguồn mở miễn phí và 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 mọi 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ẽ. Ngoài ra, tính năng Đọc tài liệu được xây dựng để cung cấp dịch vụ lưu trữ cho tài liệu của Sphinx giúp tài liệu của bạn luôn được cập nhật trên nhiều phiên bản. Cả hai đều là một bộ công cụ tuyệt vời mà các nhà phát triển và người viết nội dung kỹ thuật có thể sử dụng để tạo tài liệu về người dùng phù hợp nhất cho người dùng cuối.

Sphinx bao gồm tính năng hỗ trợ cho việc dịch tài liệu sang nhiều ngôn ngữ. Thư viện này hỗ trợ việc quản lý phiên bản để 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 phù hợp, hệ thống quản lý phiên bản này đảm bảo rằng tất cả các thay đổi được xem xét trước khi được hợp nhất vào kho lưu trữ chính. Quản lý 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 các vấn đề, yêu cầu kéo mở, v.v. Sphinx và đọc tài liệu được sử dụng bởi một danh sách các cộng đồng tuyệt vời khác như ASP.NET, Kernel, Julia, Jupyter, PHPMyadmin, Viết 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, còn phiên bản được lưu trữ trên readthedocs tại đây: [https://vlc-user-account-demo.readthedocs.io/en/latest/](https://vlc-user-document-demo.readthedocs.io/en/latest/.

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

Tôi đã tạo 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, cấu trúc này phải được những người cố vấn phê duyệt. Tức là cấu trúc đó có thể sẽ thay đổi sau khi được những người cố vấn xem xét.

MỤC TIÊU DỰ ÁN

Điều chỉnh 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 cho dễ hiểu hơn.
Thiết lập công cụ này để dịch bằng công cụ Quốc tế hoá Sphinx.
Xây dựng tài liệu dựa trên cộng đồ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 khi đọc tài liệu.

LÝ DO CHÚNG TÔI RA MẮT 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 hết tiềm năng khi bạn có khả năng giải thích cho người khác hiểu rõ về nó thông qua việc viết. Cá nhân, tôi luôn bị cuốn hút bởi những nỗ lực của cộng đồng VideoLAN trong việc tạo ra các giải pháp phần mềm miễn phí cho đa phương tiện. Tôi đã lớn lên khi còn nhỏ, 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ì nó rất to và có rất 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 làm nên tuổi thơ của 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 trong việc 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, nên việc thực hiện các lệnh trên Gitab sẽ không thành vấn đề. Hơn nữa, điều thúc đẩy tôi thực hiện các dự án tạo ra giá trị cho mọi người.
Tôi tin rằng nếu bạn muốn ai đó làm điều gì đó theo cách hiệu quả nhất có thể, hãy ghi lại điều đó. Bằng việc ghi lại các quy trình của mình, bạn giúp đảm bảo tính hiệu quả, tính nhất quán và sự an tâm cho tất cả những ai tham gia.
Tôi biết nhu cầu của người dùng VLC vì tôi là một trong số họ. Việc này sẽ giúp bạn 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 hiểu ngay từ đầu.