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ở:
- GRPC-Gateway
- Người viết nội dung 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 gian tiêu chuẩn (3 tháng)
Mô tả dự án
TÓM TẮT:
Trang web tài liệu 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 dành cho người dùng là rất quan trọng vì trang web này giúp 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 có thể 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 bản sắc doanh nghiệp của sản phẩm. Trang web tài liệu dành cho người dùng chất lượng cao là một dấu hiệu cho thấy sản phẩm của nhóm nhà phát triển đang hoạt động tốt. Nếu không có trang web tài liệu dành cho người dùng hiệu quả, người dùng có thể không biết cách thực hiện các thao tác trên một cách hiệu quả. Trang web 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ẽ và 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, tài liệu tuyệt vời chỉ cần có hoạt động giao tiếp đó và đặt trong một khung 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, kho lưu trữ gRPC-Gateway đã được chia thành 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 toàn thế giới sử dụng gRPC-Gateway và có thể muốn đọc tài liệu người dùng của nó để biết hướng dẫn về cách sử dụng gRPC-Gateway. Tuy nhiên, trang web tài liệu và tài liệu dành cho người dùng gRPC-Gateway hiện đã lỗi thời và chưa hoàn chỉnh và cộng đồng gRPC-Gateway muốn sử dụng dự án này để tái cấu trúc trang tài liệu hiện tại để cải thiện trang tài liệu 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 gRPC-Gateway.
TIỂU BANG HIỆN TẠI:
Hiện tại, trang web tài liệu về gRPC-Gateway có hai vấn đề lớn:
• Vấn đề đầu tiên là trang web tài liệu kém và lỗi thời 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 khó 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 định kiểu trang web, thêm 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 hướng dẫn và ví dụ trong thanh bên phù 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ế sơ đồ 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 trên kiểu và cấu trúc lại trang web Tài liệu hiện có.
• Vấn đề thứ hai, bạn cần tái cấu trúc các tài liệu, hướng dẫn và ví dụ hiện có, v.v. về gRPC-Gateway, có thể thực hiện được bằng cách xoá lỗi đánh máy và ngữ pháp trên các tệp, căn chỉnh đúng cách đoạn trích Go và tái cấu trúc đoạn trích Go theo định dạng Gofmt. Ngoài ra, nếu cần, chúng tôi có thể bổ sung thêm tài liệu, hướng dẫn và ví dụ nếu cần, 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à sẽ thực hiện việc này sau khi tôi hoàn thành mục tiêu chính của mình, cụ thể là tạo kiểu và tái cấu trúc trang web Tài liệu hiện có.
TẠI SAO TRANG WEB TÀI LIỆU ĐƯỢC ĐỀ XUẤT CỦA TÔI ĐƯỢC CẢI TIẾN SO VỚI TRANG WEB HIỆN TẠI?
Trang web 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. Giao diện này sẽ có giao diện đẹp hơn và giao diện người dùng đẹp hơn, với các phần và tính năng được cách điệu hợp lý, chứa hướng dẫn bằng văn bản cùng sơ đồ và hình ảnh kèm theo.
Tài liệu về gRPC-Gateway mô tả rõ ràng về phương thức và ví dụ. Nhưng nó vẫn đang sử dụng giao diện Jekyll cũ và ngày nay, chúng tôi đã có các giao diện Jekyll SSG (Trình tạo trang web tĩnh) tốt hơn. Ngoài ra, bạn cần tái cấu trúc các trang và làm cho trang trở nên hữu ích hơn cho người dùng bằng cách thêm các ví dụ và hướng dẫn mới, đồng thời cập nhật và viết lại nội dung trước đó.
CẤU TRÚC VÀ Lộ trình CỦA MỤC TIÊU VÀ Ý TƯỞNG ĐỀ 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 những cách sau:
Chuyển giao diện Hiện tại Jekyll sang giao diện mạnh mẽ và tốt hơn. Lý do sử dụng lại giao diện Jekyll là vì các nhà bảo trì sẽ dễ dàng đóng góp và hiểu quy trình làm việc của dự án vì họ đã biết khung và giao diện Jekyll hiện có tương tự như giao diện Jekyll mới.
Sau khi xem qua các chủ đề Jekyll khác nhau trên Internet, tôi nhận thấy https://id resolvebewriting.com/document-theme-jekyll/ bộ chủ đề này tốt nhất cho 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. Bạn có thể ghi đơn giản trong tệp .md. 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 trên GitHub) để cải thiện trang web. Điều này sẽ thu hút 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 phải có một hộp tìm kiếm để họ có thể tìm thấy nội dung có liên quan một cách dễ dàng và nhanh chóng.
• Phần Nhận xét:- Người dùng có thể có nhận xét và chia sẻ quan điểm của họ về các bài đăng và hướng dẫn. Họ có thể đọc lượt xem 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 với các bài đăng trên blog mới và tin tức về lộ trình và quá trình phát triển hiện tại. Vì vậy, hãy thể hiện viết blog trên trang đích.
• Phát triển nhanh:– Hầu hết các 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ẽ phản ánh 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 phải dễ dàng. Trong tương lai, nếu muốn thay đổi khung này, chúng ta sẽ sử dụng. Sau đó, việc này sẽ trở nên thật dễ dàng. Hầu hết các khung đều hỗ trợ viết Markdown, vì vậy, bạn chỉ cần di chuyển các tệp .md và một vài thay đổi là đủ.
Ở đây, tôi sẽ chia các trang trên trang web hiện có thành các phần và trang mới trên trang web :
• Trang đích:-
Trang đích phải chỉ ra 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)
- Lý do bạn nên 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 trên trang đích và cung cấp đường liên kết dẫn đến trang chi tiết.
• Trang hướng dẫn sử dụng gRPC-Gateway:-
- Hướng dẫn cài đặt.
- Bắt đầu nhanh với gRPC-Gateway.
• Trang hướng dẫn 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 mỗi bước.
• Giới thiệu về trang gRPC-Gateway:-
Danh sách tất cả người đóng góp sẽ hiển thị trong phần của nhóm Liên kết nhanh và ghi chú phát hành, các blog mới nhất sẽ được thêm vào để thu hút người dùng đọc về tin tức hiện tại của 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ờ vậy, tin tức và bản phát hành có thể được thông báo dễ dàng. 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 làm rõ các API và khái niệm của gRPC-Gateway. Cộng tác viên có thể thêm đường liên kết đến nội dung hướng dẫn của họ vào 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, sắp xếp và căn chỉnh đường liên kết và bài đăng trên trang web trên tất cả các tệp hiện có của gRPC-Gateway.
• Bổ sung tài liệu và nội dung 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 trên AWS, Nền và Sử dụng, v.v.
• Tái cấu trúc đoạn trích 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.
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 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 GitHub 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 đã quen thuộc với quy trình làm việc và cơ sở mã của gRPC-Gateway vì tôi đang đóng góp cho gRPC-Gateway từ hai tháng qua và đã hợp nhất 11 PR.