Dự án Creative Commons

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ở:
Giấy phép Creative Commons
Người viết nội dung kỹ thuật:
nimishnb
Tên dự án:
Hướng dẫn sử dụng từ vựng
Độ dài dự án:
Thời hạn tiêu chuẩn (3 tháng)

Mô tả dự án

Tóm tắt dự án

Từ vựng có tiềm năng to lớn để được dùng làm thư viện thành phần giao diện người dùng chính cho việc xây dựng trang web. Điều cần thiết là một hướng dẫn cách làm mạnh mẽ nhưng dễ hiểu đối với người mới. Thông tin quan trọng dành cho nhà phát triển, chẳng hạn như hướng dẫn về thành phần, thông số kỹ thuật về cách sử dụng và các biện pháp tinh chỉnh cấu hình, là một phần thiết yếu của mọi tài liệu. Điều này không chỉ khuyến khích người dùng hiện tại cảm nhận được cách từ vựng tiếp tục phát triển và đạt được các mốc mới, mà còn thúc đẩy việc sử dụng Từ vựng trong các dự án tương đối mới. Mục tiêu của tôi khi làm thực tập không chỉ là viết một hướng dẫn ngắn gọn về cách sử dụng các thành phần có sẵn mà còn là thiết kế và phát triển trang chủ (dẫn đến tài liệu tích hợp cho từng trang) cho Vocabulary, Vue-Vocabulary và Phông chữ.

Kế hoạch dự án

  1. Vấn đề: Tài liệu là một trong những lý do chính quyết định mức độ thành công của một thư viện nguồn mở nhất định. Khi lựa chọn bộ phần mềm cơ sở để xây dựng ứng dụng, câu hỏi chính mà các nhà phát triển nghĩ đến khi lựa chọn bộ phần mềm cơ sở để xây dựng ứng dụng là "Thư viện có được lập tài liệu đầy đủ không? Nơi này có được giữ gìn kỹ không? Công cụ này có hoạt động sử dụng và hỗ trợ khắc phục lỗi đáng kể không?”. Đây chính xác là những câu hỏi mà chúng ta nên tự đặt ra khi tìm hiểu về ý tưởng dự án này. Từ góc độ kỹ sư phần mềm:

  2. Phân tích yêu cầu: Tất nhiên, cần có một tài liệu ngắn gọn và hợp nhất cho nhu cầu của chúng ta. Việc thiếu tài liệu sẽ ảnh hưởng đến triển vọng tương lai của các ứng dụng nguồn mở và là một thành phần thiết yếu và không thể bỏ qua. Trang chủ hấp dẫn là nơi liên kết đến các tài liệu này, giúp thu hút sự quan tâm của mọi người ngay lập tức. Tài liệu phải được sắp xếp hợp lý, nhờ đó giúp quá trình đọc tài liệu diễn ra liền mạch.

  3. Thông số kỹ thuật: Tuỳ thuộc vào các yêu cầu, bạn có thể quyết định thông số kỹ thuật. Nội dung trong tài liệu có thể được tạo từ dữ liệu có trong các trang web netlify của CC, cùng với một số cảm hứng từ các tài liệu nổi tiếng như semantic-ui, scikit-learn, numpy, bootstrap, v.v. Kết quả của nhiệm vụ này sẽ là trang đích bắt buộc và hướng dẫn tài liệu đầy đủ.

Hiện tại, một số vấn đề chung liên quan đến Từ vựng, Từ vựng và Phông chữ:

  • Không có tài liệu; và ngay cả khi có, các phần của tài liệu đó cũng nằm rải rác trên các trang web của Netlify. Điều này không ngăn người dùng, nhà phát triển hoặc cộng tác viên bên ngoài sử dụng thư viện của chúng tôi.

    • Để chuyển đến một thành phần nhất định và sao chép mã tương ứng, bạn cần nhấp thêm. Một cụm từ tìm kiếm đơn giản trên Google như "Thành phần thẻ CC Vocabulary" sẽ không trả về thông tin mong muốn. Tuỳ chọn Tìm kiếm trong hướng dẫn tài liệu sẽ cải thiện đáng kể trải nghiệm người dùng.

    • Nội dung mô tả chi tiết hơn về các thành phần, mô tả các chi tiết không rõ ràng.

    • Không có tuỳ chọn chạy trực tiếp. Nhiều trang web như JSFiddle hỗ trợ tính năng chạy trực tiếp, cho phép nhà phát triển cảm nhận được thành phần mà không cần chạy toàn bộ ứng dụng để xem thành phần đó hoạt động như thế nào.

Giải pháp

Có nhiều giải pháp. Tuy nhiên, tôi sẽ đề cập đến một vài vấn đề ở đây và trình bày giải pháp cuối cùng trong phần kết luận:-

= Sử dụng readthedocs readthedocs là một giải pháp nổi tiếng để viết tài liệu cho các thư viện nguồn mở. Công cụ này dựa trên Sphinx, công cụ tài liệu về python.

Ưu điểm:

  1. Hình thức tạo tài liệu được chấp nhận rộng rãi và được các tổ chức như Etheum (Solidity) sử dụng.
  2. Tài liệu có cấu trúc tối ưu.
  3. Lưu trữ trang web tĩnh miễn phí.

Nhược điểm:

  1. Thiếu quyền kiểm soát tuyệt đối đối với kiểu.

= Sử dụng Sphinx Chúng ta cũng có thể sử dụng sphinx cho phần tài liệu, nó cung cấp các tính năng phù hợp cho mọi mục đích của chúng ta.

Ưu điểm:

  1. Công cụ python phổ biến nhất để ghi chép tài liệu.
  2. Cũng hỗ trợ tìm kiếm tài liệu.
  3. Bạn có thể ghi đè CSS mặc định bằng một CSS tuỳ chỉnh; một số chế độ kiểm soát HTML bằng cách sử dụng các tệp .rst.

Nhược điểm:

  1. Sẽ bao gồm lập trình bằng python và định dạng văn bản được tái cấu trúc (.rst). Đây là độ lệch so với các ngôn ngữ dự án được đề xuất.

= Sử dụng giao diện Jekyll Giao diện Jekyll được tích hợp trong các trang github và có các mẫu hiện có có thể được tuỳ chỉnh tuỳ theo nhu cầu của chúng ta.

Ưu điểm:

  1. Các giao diện tài liệu tạo sẵn cho mọi mục đích.
  2. Kiểu và CSS mặc định có thể bị ghi đè bằng các kiểu và CSS tuỳ chỉnh, cũng như có thể kiểm soát đối với HTML.
  3. Kéo CSS Primer mặc định để tạo các trang.
  4. Dễ dàng tích hợp với các trang GitHub.

Nhược điểm:

  1. Có thể không cung cấp được cấu trúc tài liệu phù hợp nhất.

=Sử dụng trang GitHub Các trang github chuẩn để tạo trang web tĩnh (HTML, CSS, JS).

Ưu điểm:

  1. Toàn quyền kiểm soát hầu hết mọi thứ liên quan.
  2. Linh hoạt tối đa trong việc quyết định bố cục, màu sắc và kiểu.
  3. Dễ dàng sử dụng các thành phần Từ vựng.
  4. Dễ dàng nhúng các đoạn mã và chạy đường liên kết trực tiếp.

Nhược điểm:

  1. Có thể là phương pháp tốn nhiều thời gian hơn.

= Sử dụng Haroopad Đây là giải pháp markdown thay thế.

Ưu điểm:

  1. Sẽ liên quan đến việc lập trình rắc rối ở mức tối thiểu.
  2. Tập trung vào việc viết tài liệu sao cho hoàn hảo.

Nhược điểm:

  1. Thiếu quyền kiểm soát đối với CSS.
  2. Có thể cộng đồng hỗ trợ tốt nhất hoặc không.
  3. Có thể không hỗ trợ MDX.

= Sử dụng MKDocs Đây là một giải pháp markdown thay thế khác.

Ưu điểm:

  1. Sẽ liên quan đến việc lập trình rườm rà ở mức tối thiểu (một lần nữa).
  2. Phương pháp Viết nhiều, Mã ít.

Nhược điểm:

  1. Thiếu quyền kiểm soát đối với CSS.
  2. Có thể cộng đồng sẽ không hỗ trợ tốt nhất cho bạn.
  3. Sử dụng python; có thể cần phải tạo một phiên bản Amazon S3.

= Sử dụng VueJS +StorybookJS Phương pháp này thường được sử dụng trên Vocabulary và các kho lưu trữ chị em của nó.

Ưu điểm:

  1. Bám sát các công nghệ đảm bảo hoạt động tốt, dựa trên kinh nghiệm làm việc trước đây.
  2. Quen thuộc với cơ sở mã.
  3. Không có công nghệ phù hợp trong không gian này.

Nhược điểm:

  1. Bạn cũng có thể thấy các tuỳ chọn đơn giản hơn cho cùng một mục đích.

Tóm lại, tôi cho rằng cách tiếp cận liên quan đến cách tiếp cận VueJS+Storybook (HTML,CSS,JS) có vẻ phù hợp nhất, vì tôi cũng cảm thấy thoải mái với phương pháp này. Tuy nhiên, điều này cũng có nghĩa là chúng ta sẽ không hoàn toàn bỏ qua việc phát triển ứng dụng này. Bạn cũng có thể sử dụng các thành phần CC-Vocabulary một cách khá đơn giản. Tuy nhiên, để quyết định cấu trúc của tài liệu, chúng ta chắc chắn phải cân nhắc cách nội dung được chia thành các tiêu đề phụ trong tài liệu readthedocs. Tôi rất ấn tượng với trang web Semantic-UI (sử dụng StoryBook) vì trang web này có giao diện tối giản và người dùng có thể dễ dàng biết được mình muốn gì chỉ sau vài lượt nhấp. Ngoài Semantic-UI, tôi cũng đã xem xét Material Design, Primer, Bootstrap, Carbon Design, v.v. để dùng làm hướng dẫn tạo kiểu giao diện người dùng và hệ thống thiết kế cho công việc của mình. Chúng ta cũng có thể tìm kiếm các giao diện tài liệu Jekyll tạo sẵn để lấy cảm hứng.