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ở:
- 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 gian 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ì nó cần là một hướng dẫn cách thực hiện mạnh mẽ nhưng thân thiện với người ngoài 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, thông số kỹ thuật về cách sử dụng và các thay đổi về 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 tiếp tục phát triển như thế nào và đạt được các mốc mới như thế nào, mà còn khuyến khích 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 của tôi với tư cách là thực tập sinh không chỉ bao gồm việc viết ra một hướng dẫn đơn giản để sử dụng các thành phần có sẵn mà còn là việc 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) về Từ vựng, 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. Câu hỏi chính mà các nhà phát triển nghĩ đến khi chọn một nhóm công nghệ phù hợp để xây dựng ứng dụng là "Thư viện có được ghi lại đầy đủ không? Xe có được bảo trì tốt không? Nó có được hỗ trợ đáng kể về mặt sử dụng và lỗi không?”. Đây chính là những câu hỏi mà chúng ta nên tự đặt ra khi tìm hiểu về ý tưởng của dự án này. Từ góc độ kỹ thuật phần mềm:
Phân tích yêu cầu: Chúng ta cần ngay một tài liệu ngắn gọn và tổng hợp để đáp ứng các nhu cầu của mình. Việc thiếu tài liệu gây ảnh hưởng đến quan điểm 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 đến những tài liệu này cần có một trang chủ hấp dẫn và thu hút được 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 hợp lý để đảm bảo nội dung tài liệu diễn ra suôn sẻ.
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 này 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ố ý tưởng từ các tài liệu nổi tiếng như semantic-ui, sInsightsit-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 hoàn chỉnh.
Một số vấn đề chung hiện tại liên quan đến Từ vựng, Từ vựng và Phông chữ:
Thiếu tài liệu và ngay cả khi có một số phần, một số tài liệu vẫn nằm rải rác khắp các trang web của YouTube. 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 phải 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 chỉ đơn giản tìm kiếm một nội dung như "Từ vựng thành phần thẻ CC trên Google", thì kết quả 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ẽ giúp cải thiện đáng kể trải nghiệm người dùng.
Một đoạn mô tả chi tiết hơn bằng văn bản về các thành phần, mô tả những 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ợ việc chạy phiên bản hoạt động. Điều này cho phép nhà phát triển làm quen với 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 điều 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ở. Bộ công cụ này dựa trên Sphinx, công cụ 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 định kiểu.
= Sử dụng Sphinx Về bản chất, chúng ta cũng có thể sử dụng Sphinx cho phần tài liệu, vì nó cung cấp các tính năng hữu ích cho mọi 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ố quyền kiểm soát HTML bằng cách sử dụ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 các ngôn ngữ dự án đề xuất.
= Sử dụng giao diện Jekyll Các giao diện của 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:
- Các giao diện tài liệu được tạo sẵn 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.
- Lấy CSS Primer mặc định để tạo 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:
- Có toàn quyền kiểm soát hầu hết mọi nội dung có liên quan.
- 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à các đườ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 Thay vào đó, bạn sẽ có một giải pháp đánh dấu thay thế.
Ưu điểm:
- Sẽ cần nhiều công sức lập trình 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ó sự hỗ trợ tốt nhất từ cộng đồng.
- Có thể không hỗ trợ MDX.
= Sử dụng MKDocs Cách này cung cấp một giải pháp đánh dấu khác.
Ưu điểm:
- Sẽ cần đến việc lập trình linh hoạt tối thiểu (một lần nữa).
- Viết nhiều hơn, ít phải viết 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ể cần phải tạo một thực thể Amazon S3.
= Sử dụng VueJS +StorybookJS Phương pháp này thường được dùng trên Từ vựng và các kho lưu trữ tương ứng.
Ưu điểm:
- Bám sát những công nghệ đảm bảo hoạt động tốt, dựa trên những kinh nghiệm làm việc trước đây.
- Quen thuộc với cơ sở mã.
- Không có công nghệ nào đắc lực trong lĩnh vực này.
Nhược điểm:
- Các tuỳ chọn đơn giản hơn cũng có thể xuất hiện cho cùng mục đích.
Sau đây, tôi cho rằng phương pháp tiếp cận sử dụng 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 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 phân chia nội dung giữa các tiêu đề phụ trong tài liệu readthedocs. Tôi ấ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 cú nhấp. Ngoài Semantic-UI, tôi cũng đã xem xét Material Design, Primer, Bootstrap, Carbon Design, v.v. để sử dụng làm hướng dẫn định kiểu 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ể tra cứu các chủ đề tài liệu Jekyll tạo sẵn để tìm cảm hứng tương tự.