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ở:
- Cổng gRPC
- Tác giả kỹ thuật:
- iamrajiv
- Tên dự án:
- Tái cấu trúc trang web Tài liệu hiện có của gRPC-Gateway
- Thời lượng dự án:
- Thời hạn tiêu chuẩn (3 tháng)
Mô tả dự án
TÓM TẮT:
Trang web tài liệu dành cho người dùng được thiết kế để hỗ trợ người dùng cuối sử dụng sản phẩm hoặc dịch vụ. Trang web tài liệu người dùng tốt rất quan trọng vì nó cung cấp một kênh để 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 và thủ thuật 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. Trang web 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ó trang web 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ả. Trang web tài liệu dành cho người dùng có thể đóng vai trò then chốt trong việc đảm bảo sự thành công của sản phẩm, vì giao tiếp hiệu quả là trọng tâm của mọi doanh nghiệp hoặc sản phẩm. Tài liệu tuyệt vời chỉ coi hoạt động giao tiếp đó và đưa vào một khung dễ quản lý mà ai cũng có thể sử dụng để thành công.
Tại thời điểm viết bài này, kho lưu trữ gRPC-Gateway đã được phát triển khoảng 1200 lần và 184 người đã đóng góp vào kho lưu trữ này. Điều này cho thấy rằng rất nhiều người trên khắp thế giới sử dụng gRPC-Gateway và có thể muốn đọc tài liệu người dùng của mình để được hướng dẫn về cách sử dụng gRPC-Gateway. Tuy nhiên, tài liệu người dùng và trang web tài liệu của gRPC-Gateway hiện đã lỗi thời và chưa hoàn chỉnh. Cộng đồng gRPC-Gateway muốn sử dụng dự án này để tái cấu trúc trang web tài liệu hiện có, cải thiện trang web tài liệu để người dùng cuối có trải nghiệm liền mạch khi sử dụng gRPC-Gateway.
TRẠNG THÁI HIỆN TẠI:
Hiện tại, trang web tài liệu gRPC-Gateway có hai vấn đề lớn:
• Vấn đề đầu tiên là trang web tài liệu không tốt và lỗi thời, tức là kiểu và cấu trúc của trang web và giao diện được sử dụng đã lỗi thời, không đầy đủ, khó điều hướng hoặc tìm thông tin, không bao gồm nhiều tính năng của trang web tài liệu tốt. Việc tái cấu trúc trang web Tài liệu hiện có của gRPC-Gateway sẽ bao gồm việc tạo kiểu cho trang web, thêm các tính năng như tìm kiếm tài liệu, v.v., cải thiện giao diện người dùng của trang web, sắp xếp các hướng dẫn và ví dụ trong một thanh bên thích hợp và cập nhật sơ đồ quy trình và hình ảnh hiện có bằng cách thiết kế một sơ đồ quy trình mới, v.v. Đây sẽ là mục tiêu chính của tôi và công việc của tôi sẽ dựa nhiều hơn vào việc tạo kiểu và tái cấu trúc trang web Tài liệu hiện có.
• Vấn đề thứ hai là cần phải tái cấu trúc các tài liệu, hướng dẫn và ví dụ hiện có, v.v. của gRPC-Gateway. Bạn có thể thực hiện việc này bằng cách loại bỏ các lỗi đánh máy và ngữ pháp trên các tệp, căn chỉnh đúng các đoạn mã Go và tái cấu trúc các đoạn mã Go theo định dạng của Gofmt. Ngoài ra, nếu cần, chúng ta có thể thêm tài liệu, hướng dẫn và ví dụ khác hoặc sử dụng lại các tệp hiện có sau khi tái cấu trúc. Đây là mục tiêu phụ của tôi và tôi sẽ thực hiện việc này sau khi hoàn thành mục tiêu chính, tức là tạo kiểu và tái cấu trúc trang web Tài liệu hiện có.
TRANG WEB GIẤY TỜ MÀ TÔI ĐỀ XUẤT CÓ GÌ NỔI BẬT HƠN TRANG WEB HIỆN TẠI?
Trang web tài liệu do người dùng đề 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. Giao diện người dùng và giao diện sẽ đẹp hơn với các phần và tính năng được cách điệu tốt, chứa hướng dẫn bằng văn bản cũng như sơ đồ quy trình và hình ảnh liên quan.
Tài liệu về gRPC-Gateway cung cấp nội dung mô tả chi tiết về phương thức và ví dụ. Tuy nhiên, trang web này vẫn đang sử dụng giao diện Jekyll cũ và hiện tại, chúng ta có các giao diện Jekyll SSG (Trình tạo trang web tĩnh) tốt hơn. Ngoài ra, chúng ta cũng cần phải sắp xếp lại cấu trúc các trang để tăng tính hữu ích cho người dùng bằng cách thêm các ví dụ và hướng dẫn mới, cũng như cập nhật và viết lại những nội dung trước đó.
CẤU TRÚC VÀ Lộ trình CỦA MỤC TIÊU VÀ Ý TƯỞNG ĐƯỢC ĐỀ XUẤT:
MỤC TIÊU CHÍNH CỦA DỰ ÁN NÀY:-
Bạn có thể triển khai các mục tiêu và ý tưởng trên theo các cách sau:
Chuyển giao diện Jekyll hiện tại sang giao diện tốt hơn và mạnh mẽ hơn. Lý do sử dụng lại giao diện Jekyll là để người bảo trì dễ dàng đóng góp và hiểu quy trình làm việc của dự án vì họ đã biết về khung và giao diện Jekyll hiện có tương tự như giao diện Jekyll mới.
Sau khi xem qua nhiều giao diện Jekyll trên Internet, tôi nhận thấy bộ giao diện https://idratherbewriting.com/documentation-theme-jekyll/ phù hợp nhất với trang web tài liệu gRPC-Gateway vì tính năng sau:
• Markdown:- Để người viết nội dung kỹ thuật không phải lo lắng về việc cài đặt. Họ có thể viết đơn giản trong tệp .md. Bất kỳ ai cũng có thể nhấp vào nút chỉnh sửa xuất hiện trên trang web (tính năng mới) và đóng góp (chỉnh sửa/đề xuất thay đổi cho trang trong GitHub) để cải thiện trang web. Điều này sẽ khuyến khích người dùng thêm nội dung mới hoặc chỉnh sửa nội dung để cải thiện nội dung.
• Tìm kiếm Tài liệu:- Người dùng nên có hộp tìm kiếm để họ có thể dễ dàng và nhanh chóng tìm ra các nội dung có liên quan.
• Phần nhận xét:– Người dùng có thể nhận xét và chia sẻ quan điểm của mình về các bài đăng và hướng dẫn. Họ có thể đọc thành phần hiển thị của người khác trên tài liệu về dự án.
• Ghi chú phát hành và blog mới: Trang web phải được cập nhật bằng các bài đăng trên blog mới và tin tức về lộ trình và hoạt động phát triển hiện tại. Vì vậy, kiểu viết blog nên xuất hiện trên trang đích.
• Phát triển nhanh: – Hầu hết khung SSG (Trình tạo trang web tĩnh) đang chạy trong máy chủ và các thay đổi trong tệp sẽ được thể hiện ngay lập tức trong giao diện người dùng. Ngoài ra, quy trình triển khai và xây dựng cũng phải dễ dàng. Trong tương lai, nếu muốn thay đổi khung, chúng ta sẽ sử dụng. Sau đó, bạn sẽ thấy việc này rất dễ dàng. Hầu hết các khung đều hỗ trợ việc viết Markdown, vì vậy, bạn chỉ cần di chuyển các tệp .md và thực hiện một vài thay đổi là đủ.
Ở đây, tôi sẽ chia các trang hiện có trên trang web thành các phần và trang mới trên trang web :
• Trang đích:-
Trang đích phải nêu bật các tính năng chính của gRPC-Gateway.
- Bắt đầu sử dụng gRPC-Gateway (chuyển hướng đến hướng dẫn sử dụng)
- Hướng dẫn cài đặt đơn giản (các lệnh ngắn gọn)
- Lý do sử dụng gRPC-Gateway
- Dự án sử dụng gRPC-Gateway
Vì vậy, ý tưởng cơ bản là thay vì viết đoạn mô tả dài, hãy trình bày các điểm chính trong trang đích và cung cấp đường liên kết để tìm hiểu chi tiết.
• Trang Hướng dẫn sử dụng gRPC-Gateway:-
- Hướng dẫn cài đặt.
- Bắt đầu nhanh bằng gRPC-Gateway.
• Trang hướng dẫn dành cho nhà phát triển gRPC-Gateway:-
Hướng dẫn phát triển, Hướng dẫn đóng góp, Thiết lập Git, Quy tắc ứng xử, Thiết lập tài liệu, Quy trình phát triển, v.v. đều trỏ đến các trang tương tự bên trong. Vì vậy, bạn cần tái cấu trúc và sắp xếp lại tất cả các tệp. Trang phát triển chính phải chứa tất cả các trang này và siêu liên kết sẽ được tạo trong từng bước.
• Giới thiệu về trang gRPC-Gateway:-
Danh sách tất cả cộng tác viên phải có mặt trong các phần của nhóm Đường liên kết nhanh và ghi chú phát hành. Chúng tôi sẽ thêm các blog mới nhất để thu hút người dùng đọc tin tức hiện tại về gRPC-Gateway.
• Trang blog, ghi chú phát hành và hướng dẫn:-
Tôi cảm thấy trang web đó nên có lựa chọn viết blog. Nhờ đó, bạn có thể dễ dàng thông báo tin tức và bản phát hành. Trang hướng dẫn sẽ chứa một số bài nói chuyện và bài viết phổ biến giúp làm rõ các API và khái niệm về gRPC-Gateway. Cộng tác viên có thể thêm đường liên kết đến hướng dẫn của họ trong trang hướng dẫn.
Sau khi hoàn thành tác vụ ở trên, hãy cập nhật các thay đổi tương tự trong nhánh v2 và thực hiện ngay cả với nhánh chính của gRPC-Gateway.
MỤC TIÊU PHỤ CỦA DỰ ÁN NÀY:-
Bạn cần thực hiện các thay đổi khác để tài liệu về gRPC-Gateway trở nên mạnh mẽ và dễ đọc hơn:-
• Sửa lỗi ngữ pháp, lỗi đánh máy cũng như sắp xếp và căn chỉnh đường liên kết và bài đăng trong trang web trên tất cả các tệp hiện có của gRPC-Gateway.
• Thêm tài liệu và nội dung khác nếu cần trong gRPC-Gateway vì hầu hết các tính năng đều có tài liệu rất ngắn như trong phần Tài liệu của trang web về AWS, Nền và Cách sử dụng, v.v.
• Tái cấu trúc các đoạn mã Go gRPC-Gateway theo định dạng Gofmt
Sau khi hoàn thành tác vụ ở trên, hãy cập nhật các thay đổi tương tự trong nhánh v2 và thực hiện ngay cả với nhánh chính của gRPC-Gateway.
LÝ DO TÔI LÀ NGƯỜI PHÙ HỢP VỚI 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 mọi hệ thống quản lý phiên bản, vì vậy, việc thực hiện các lệnh trên GitHub 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 đã quen thuộc với quy trình làm việc và cơ sở mã của gRPC-Gateway vì tôi đã đóng góp cho gRPC-Gateway từ hai tháng qua và đã hợp nhất 11 PR.