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ở:
- Nền tảng điện toán đám mây gốc (CNCF)
- Người viết nội dung kỹ thuật:
- Shriti
- Tên dự án:
- Cải thiện tài liệu về SMI và các lưới dịch vụ liên quan
- Thời lượng dự án:
- Thời gian tiêu chuẩn (3 tháng)
Mô tả dự án
Công nghệ Service Mesh về cơ bản nhằm mục đích cung cấp giá trị cho số lượng dịch vụ ngày càng tăng, bằng cách xử lý tất cả các nhu cầu về bảo mật, quản lý và giám sát của bạn. Giao diện lưới dịch vụ (SMI) xác định một tập hợp API cho các trường hợp sử dụng lưới dịch vụ phổ biến nhất (chính sách lưu lượng truy cập, đo từ xa và dịch chuyển) và cho phép khả năng tương thích giữa các lưới dịch vụ, là các lớp cơ sở hạ tầng chuyên dụng để xử lý hoạt động giao tiếp giữa các dịch vụ trong môi trường vi dịch vụ. Việc chuẩn hoá các giao diện này sẽ nâng cao trải nghiệm người dùng cuối. Do đó, mục tiêu trong tương lai của SMI và các lưới dịch vụ liên quan sẽ là mục tiêu trong tương lai.
Trạng thái hiện tại:
Hướng dẫn sử dụng: SMI là một dự án hộp cát tương đối mới, được đóng góp cho CNCF vào tháng 4 năm 2020. Do đó, dự án này thiếu tài liệu dành cho người dùng cuối. Meshery là một mặt phẳng quản lý dịch vụ có dịch vụ đo điểm chuẩn hiệu suất cho tất cả các loại dịch vụ hỗ trợ việc sử dụng, định cấu hình, vận hành và quản lý hiệu suất của nhiều lưới dịch vụ, đồng thời tích hợp việc thu thập và hiển thị số liệu từ các ứng dụng chạy trên bất kỳ lưới dịch vụ nào. Do đó, tôi muốn bắt đầu bằng một hướng dẫn dành cho Meshery, đây sẽ là điểm xuất phát cho toàn bộ cộng đồng người dùng SMI.
Hướng dẫn cho người dùng: Trong số các nền tảng SMI hiện có: Ứng dụng mẫu, Tìm hiểu Layer5, hiện đóng vai trò là thiết bị học tập cho SMI và là ứng dụng mẫu để xác thực thông số kỹ thuật SMI. Nhưng nếu không, các dự án SMI hoàn toàn thiếu hướng dẫn của người dùng cuối. Đây là một trở ngại nghiêm trọng vì tính chất kỹ thuật rất cao của các dự án. Meshery là ứng dụng hoàn hảo để giới thiệu những lợi ích và cách sử dụng SMI cũng như lưới dịch vụ liên quan, vì vậy, tôi sẽ sử dụng nó làm công cụ cơ bản để thể hiện các tính năng của SMI.
Tài liệu về API: Hiện không tồn tại. SMI và nhiều dự án liên quan có điểm cuối API được xác định trên một nền tảng; ví dụ: Meshery có các điểm cuối được xác định tại server.go (https://github.com/layer5io/gridery/blob/master/router/server.go), nhưng các điểm cuối này không được nhận xét hoặc ghi lại bên ngoài. Vấn đề này có thể được giải quyết bằng tài liệu có ý nghĩa về API và có thể được cải thiện bằng cách thêm các phương thức để người dùng kiểm thử các điểm cuối và xem trước các tính năng của API.
Phân tích:
Hướng dẫn cho người dùng được tạo để cho phép người dùng tương tác và chạy thử nghiệm Phần mềm. Các quảng cáo này cần có tính tương tác và hấp dẫn về mặt thẩm mỹ để duy trì sự chú ý của người dùng và quan trọng nhất là dễ sử dụng.
Tuy nhiên, để viết hoặc lưu trữ Hướng dẫn người dùng, nên sử dụng định dạng nội dung hoàn chỉnh hơn vì Hướng dẫn sử dụng thường đóng vai trò như một hướng dẫn tham khảo hoặc nơi để khắc phục nhanh các vấn đề. Thay vì có tính tương tác, các thành phần này cần có cấu trúc hợp lý và tập trung vào việc cải thiện sự rõ ràng, mạch lạc và luồng người dùng hợp lý.
Giải pháp khả thi cho vấn đề này là tạo các Hướng dẫn sử dụng riêng biệt bằng cách sử dụng Google Codelabs và một Hướng dẫn sử dụng độc lập với sự trợ giúp của Jekyll và cuối cùng là tích hợp chúng vào với tài liệu API để cung cấp trải nghiệm toàn diện cho cả người dùng cuối và cộng tác viên trong tương lai.
Đối tượng mục tiêu: Các dự án SMI cung cấp các phương pháp triển khai và vận hành, môi trường học tập và điểm chuẩn hiệu suất cho tất cả các dự án thuộc các dự án này. Dịch vụ này phục vụ cho cả cá nhân và tổ chức.
Hướng dẫn người dùng: Tôi sẽ nhắm mục tiêu đến người dùng mới bắt đầu, không giả định về kiến thức CNTT có sẵn từ phía người dùng. Mục tiêu: Người dùng mới bắt đầu Lý do: Chủ yếu dùng làm tài liệu hướng dẫn tham khảo rộng lớn, cần được cập nhật theo thời gian. Nội dung này bao gồm giải thích chuyên sâu và mẹo hữu ích để đảm bảo người dùng có tất cả thông tin cần thiết để thiết lập và làm việc với lưới dịch vụ. Phần Hướng dẫn sẽ trở nên hấp dẫn hơn và thân thiện với người dùng hơn bằng cách thêm video, hình ảnh, ảnh chụp màn hình và ảnh GIF vào nếu cần.
Hướng dẫn cho người dùng: Mục tiêu: Người dùng mới bắt đầu Lý do: Trọng tâm là các hướng dẫn sẽ lôi cuốn và hấp dẫn về mặt thẩm mỹ để duy trì sự chú ý của người dùng, đồng thời giúp quá trình kiểm thử phần mềm diễn ra suôn sẻ, từ đó giúp bạn hiểu rõ hơn về Giao diện lưới dịch vụ.
Tài liệu về thiết bị đầu cuối API: Mục tiêu: Người dùng nâng cao Lý do: Phần này tập trung vào việc sử dụng các tính năng phức tạp hơn của lưới dịch vụ, dành cho những người dùng nâng cao có kiến thức cơ bản về CNTT. Người dùng thành thạo sẽ tìm kiếm các hướng dẫn ngắn gọn và có thể sử dụng làm hướng dẫn tham khảo nếu cần. Tài liệu về Điểm cuối phải được viết theo cách sao cho dễ dàng cập nhật mà không ảnh hưởng đến tính chính xác hoặc tính nhất quán. Bạn nên thực hiện quy trình tự động.
Tài nguyên: Hướng dẫn cho người dùng: Lớp học lập trình Google Developers – Dùng để tạo các hướng dẫn tương tác và toàn diện dành cho người dùng cuối. Lợi ích: – Có thể tạo hướng dẫn về hộp cát. – Có phương pháp tiếp cận thực tế. – Viết bằng Google Tài liệu và hỗ trợ văn bản Markdown. – Có thể theo dõi bằng Google Analytics – Dễ dàng quan sát lưu lượng truy cập của người dùng. – Dễ sử dụng. Sản xuất các video hướng dẫn đẹp mắt, cho phép người dùng tương tác trực tiếp với phần mềm mà không cần đầu tư trực tiếp.
Bạn có thể cải thiện và triển khai lớp học lập trình của Google một cách dễ dàng bằng cách sử dụng dự án CLaaT (Lớp học lập trình dưới dạng thực thể) – Đây là chương trình cung cấp một công cụ dòng lệnh dùng để chuyển đổi các hướng dẫn viết trong Google Tài liệu bằng cách sử dụng Markdown thành định dạng lớp học lập trình (HTML).
Hướng dẫn sử dụng: Jekyll – Tài liệu hiện có về gridery.io (bạn có thể tìm thấy tại đây) được lưu trữ trên Jekyll và sử dụng giao diện Tài liệu Jekyll. Công cụ này sử dụng Markdown, liquid, HTML và CSS để tạo ra các trang web tĩnh và sẵn sàng lưu trữ cũng như chạy trên môi trường phát triển Ruby. Lợi ích: – Có thể lưu trữ trang web trực tiếp từ kho lưu trữ GitHub. – Đây là một Dự án được hỗ trợ hiệu quả với một cộng đồng rất tích cực – Bạn chỉ cần thêm Hướng dẫn người dùng và các tính năng nâng cao vào tài liệu SMI và Meshery hiện có mà không phải bận tâm đến việc chuyển sang một nền tảng khác.
Tài liệu về API: Swagger (hoặc có thể là Swaggo) sẽ được dùng để tạo tài liệu về API cho SMI và Meshery. Đây là một giải pháp tinh tế để viết tài liệu API. Lợi ích: – Tài liệu từ thiết kế API của bạn: Đảm bảo tài liệu luôn được cập nhật khi API của bạn phát triển. - Tài liệu từ thiết kế API của bạn: Có thể được tạo tự động từ các định nghĩa API. - Duy trì nhiều phiên bản tài liệu - Thiết kế API tuỳ chỉnh
Mục tiêu dự án: – Sử dụng Lớp học lập trình dành cho nhà phát triển của Google để tạo hướng dẫn tương tác cho người dùng cuối về SMI và các lưới dịch vụ có liên quan bằng cách sử dụng Meshery làm công cụ. – Tạo hướng dẫn người dùng cuối bằng Jekyll dành cho lưới dịch vụ. – Sử dụng Swagger để tạo tài liệu về điểm cuối API cho SMI. – Hướng cộng đồng dự án đi vào hoạt động để người dùng hoặc nhà phát triển hiện tại và trong tương lai có thể dễ dàng tiếp tục thêm dự án vào dự án dưới sự hướng dẫn và điều phối của cộng đồng SMI.
Tiến trình: Tiến trình đề xuất có thể tham khảo tại đây: https://docs.google.com/document/d/1If2mtBdWZer4qrh66NfXOWBx_3-tiA09jnoPMqy2lqs/edit#bookmarks=kix.j1b6m64eubsl
Cấu trúc: Bạn có thể tìm thấy cấu trúc đề xuất cho Hướng dẫn sử dụng tại đây: https://docs.google.com/document/d/1A3YYAMUTe06MojNWo8hdF4KZbvr-qVaaA2myzWeshHQ/edit?usp=sharing
Tại sao có dự án này? Cộng đồng lưới dịch vụ đang mở rộng với tốc độ cực nhanh nhờ hoạt động tích hợp gần đây dưới dạng dự án hộp cát vào CNCF. Tuy nhiên, dự án này đang thiếu tài liệu một cách nghiêm trọng, cho cả người dùng cuối và nhà phát triển. Trước đây, tôi đã thử nhiều lưới dịch vụ, bao gồm cả trình liên kếtD với ứng dụng EmojiVoto, Istio với ứng dụng Bookinfo và Lãnh sự của Hashicorp. Tôi cũng đã thử phân tách lưu lượng truy cập SMI và đã triển khai nhiều quy tắc xác thực cho cấu hình lưới dịch vụ của mình. Quá trình học tập này rất thú vị nhưng đòi hỏi kỹ thuật cao và có thể gây khó khăn cho cả người dùng mới cũng như nhà phát triển. Họ đang tìm cách tham gia vào cộng đồng lưới dịch vụ hoặc sử dụng lưới dịch vụ cho các dự án cá nhân hoặc chuyên nghiệp của riêng họ. Tôi muốn thu hẹp khoảng cách này. Bạn chỉ có thể thực hiện việc này thông qua các hướng dẫn và tài liệu hướng dẫn hiệu quả và đầy đủ.