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 Google Phần Tài liệu.
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
- Thời lượng dự án:
- Thời lượng 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 để xây dựng trang web. Những gì Lớp học cần là một hướng dẫn cách thực hiện hữu ích nhưng phù hợp với người không có chuyên môn. Thông tin quan trọng dành cho nhà phát triển như hướng dẫn về thành phần, quy cách sử dụng và điều chỉnh cấu hình là một phần thiết yếu trong 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 biết từ vựng đang tiếp tục phát triển như thế nào và đạt được những cột 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 hơn. Kết quả mong muốn trong thời gian tôi là thực tập sinh không chỉ bao gồm việc viết ra một hướng dẫn vô nghĩa để sử dụng các thành phần có sẵn mà còn thiết kế và phát triển một trang chủ (dẫn đến một tài liệu tích hợp cho mỗi loại) về Từ vựng, Vue-Từ vựng và Phông chữ.
Kế hoạch dự án
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 chọn một nhóm công nghệ phù hợp để xây dựng ứng dụng, câu hỏi chính mà các nhà phát triển nghĩ đến là: "Thư viện có được ghi lại đầy đủ không? Địa điểm đó có được duy trì tốt không? Nó có hỗ trợ đáng kể về cách sử dụng và lỗi không?”. Đây chính xác là những câu hỏi mà chúng ta nên tự hỏi khi bàn về ý tưởng dự án này. Từ góc độ kỹ thuật phần mềm:
Phân tích yêu cầu: Hiện chúng tôi cần có một tài liệu ngắn gọn và hợp nhất để đáp ứng các nhu cầu của mình. Việc thiếu tài liệu làm ảnh hưởng đến triển vọng tương lai của các ứng dụng nguồn mở và cho đến nay, là một thành phần thiết yếu và không nhỏ. Việc liên kết tới những tài liệu này cần phải tạo ra một trang chủ hấp dẫn, thu hút sự quan tâm của mọi người ngay lập tức. Bạn nên sắp xếp tài liệu một cách hợp lý để đảm bảo quá trình đọc diễn ra liền mạch.
Thông số kỹ thuật: Tuỳ thuộc vào 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 của CC netlify, cùng với một số nguồn cảm hứng từ các tài liệu nổi tiếng như semantic-ui, sAlertit-learn, numpy, bootstrap, v.v. Đầu ra của nhiệm vụ này sẽ là trang đích cần thiết và hướng dẫn tài liệu hoàn chỉnh.
Hiện tại, một số vấn đề chung liên quan đến Từ vựng, Ngôn từ Vue và Phông chữ:
Tài liệu không phải là tài liệu; và ngay cả khi có một vài tài liệu, một số phần của tài liệu đó vẫn rải rác khắp các trang web Internet. Việc này không cho phép 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.
Bạn cần nhấp thêm một lần để chuyển đến một thành phần nhất định và sao chép mã tương ứng của thành phần đó. Nếu bạn tìm kiếm đơn giản trên Google như "Từ vựng CC Thành phần của thẻ", thì hệ thống sẽ không trả về thông tin mong muốn. Tuỳ chọn Tìm kiếm trong tài liệu hướng dẫn sẽ giúp cải thiện đáng kể trải nghiệm người dùng.
Mô tả chi tiết hơn bằng văn bản một chút về các thành phần, mô tả những chi tiết không rõ ràng.
Không có lựa chọn chạy trực tiếp. Nhiều trang web như JSFiddle hỗ trợ quy trình chạy trực tiếp. Điều này cho phép nhà phát triển tìm hiểu về thành phần mà không cần chạy toàn bộ ứng dụng để thấy thành phần đó hoạt động.
Giải pháp
Có thể có nhiều giải pháp. Tuy nhiên, tôi sẽ đề cập đến một vài phần sau đây và trình bày giải pháp cuối cùng của tôi trong phần kết luận:
= Sử dụng readthedocs readthedocs là một giải pháp phổ biến để viết tài liệu cho thư viện nguồn mở. API này dựa trên Sphinx, một công cụ lập tài liệu về python.
Ưu điểm:
- Hình thức tạo tài liệu được chấp nhận rộng rãi, được các tổ chức như Ethereum (Solidity) sử dụng.
- Tài liệu có cấu trúc tối ưu.
- Lưu trữ tĩnh miễn phí.
Nhược điểm:
- Thiếu quyền kiểm soát tuyệt đối đối với kiểu.
= Sử dụng Sphinx Về bản chất, chúng tôi cũng có thể sử dụng nhân sư (Sphinx) trong phần tài liệu, nó cung cấp các tính năng tốt cho tất cả mục đích của chúng ta.
Ưu điểm:
- Công cụ python phổ biến nhất cho tài liệu.
- Cũng hỗ trợ tìm kiếm tài liệu.
- Bạn có thể ghi đè CSS mặc định bằng một CSS tuỳ chỉnh; một số chức năng kiểm soát HTML bằng tệp .rst.
Nhược điểm:
- Sẽ liên quan đến việc lập trình bằng python và định dạng văn bản có cấu trúc lại (.rst). Đây là một sự khác biệt so với ngôn ngữ dự án đề xuất.
= Sử dụng Chủ đề Jekyll Các chủ đề Jekyll được tích hợp trong các trang github và có sẵn các mẫu có sẵn có thể được tuỳ chỉnh theo nhu cầu của chúng tôi.
Ưu điểm:
- Sẵn sàng tạo các chủ đề tài liệu cho mọi mục đích.
- CSS và kiểu mặc định có thể bị ghi đè bằng CSS và kiểu tuỳ chỉnh, cũng như kiểm soát HTML.
- Kéo CSS Primer mặc định để tạo các trang.
- Dễ dàng tích hợp với các trang GitHub.
Nhược điểm:
- Có thể không cung cấp cấu trúc tài liệu tốt nhất.
=Sử dụng các trang GitHub Các trang github tiêu chuẩn để xây dựng trang web tĩnh của chúng tôi (HTML, CSS, JS).
Ưu điểm:
- Toàn quyền kiểm soát hầu hết mọi nội dung được đề cập.
- Linh hoạt tối đa trong việc quyết định bố cục, màu sắc và kiểu cách.
- Dễ dàng sử dụng các thành phần Từ vựng.
- Dễ dàng nhúng các đoạn mã và đường liên kết chạy trực tiếp.
Nhược điểm:
- Có thể là một phương pháp tốn nhiều thời gian hơn.
= Sử dụng Haroopad Việc này sẽ đưa ra một giải pháp thay thế cho Markdown.
Ưu điểm:
- Sẽ mất nhiều công sức viết mã nhất.
- Trọng tâm sẽ là viết tài liệu một cách hoàn hảo.
Nhược điểm:
- Thiếu quyền kiểm soát đối với CSS.
- Có thể có hoặc không có cộng đồng hỗ trợ tốt nhất.
- Có thể không hỗ trợ giao thức MDX.
= Sử dụng MKDocs Giải pháp thay thế cho Markdown.
Ưu điểm:
- Sẽ cần đến mức độ lập trình linh hoạt tối thiểu (lại).
- Viết nhiều hơn, ít lập trình hơn.
Nhược điểm:
- Thiếu quyền kiểm soát đối với CSS.
- Có thể không được cộng đồng hỗ trợ tốt nhất.
- Sử dụng python; bạn có thể phát sinh thêm nhu cầu quay một phiên bản Amazon S3.
= Sử dụng VueJS +StorybookJS Phương pháp này thường được áp dụng trong phần Từ vựng và các kho lưu trữ tương tự.
Ưu điểm:
- Bám sát các công nghệ đảm bảo hoạt động hiệu quả dựa trên kinh nghiệm làm việc trước đây.
- Quen thuộc với cơ sở mã.
- Không có công nghệ đắc lực trong lĩnh vực này.
Nhược điểm:
- Bạn cũng có thể thấy các lựa chọn đơn giản hơn cho cùng mục đích.
Tóm lại, tôi thấy phương pháp 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 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 tôi sẽ không cố gắng hết sức để phát triển ứng dụng này. Việc sử dụng các thành phần CC-Từ vựng cũng 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 nên xem xét cách nội dung được phân chia giữa 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 tìm được nội dung mình muốn chỉ sau vài lượt nhấp. Ngoài Giao diện người dùng ngữ nghĩa, tôi cũng đã tìm hiểu về Material Design, Primer, Khởi động, Carbon Design, v.v. để dùng làm hướng dẫn định kiểu cho giao diện người dùng và hệ thống thiết kế cho công việc của tôi. Chúng ta cũng có thể tham khảo các chủ đề tài liệu tạo sẵn về Jekyll để tìm ý tưởng tương tự.