Trang này được dịch bởi Cloud Translation API.

Dự án Cloud Native Computing Foundation (CNCF)

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ở:: Cloud Native Computing Foundation (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 mạng dịch vụ có liên quan
Thời lượng dự án:: Thời hạn tiêu chuẩn (3 tháng)

Mô tả dự án

Về cơ bản, Công nghệ lưới dịch vụ hướng đến việc cung cấp giá trị cho số lượng dịch vụ ngày càng tăng bằng cách xử lý mọi nhu cầu 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à chuyển đổi) và cho phép khả năng tương thích giữa các lưới dịch vụ. Đây 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 dịch vụ vi mô. Việc chuẩn hoá các giao diện này sẽ mang lại trải nghiệm nâng cao cho người dùng cuối, do đó, đây là mục tiêu trong tương lai của SMI và các mạng dịch vụ có liên quan.

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 quyên góp cho CNCF vào tháng 4 năm 2020. Do đó, dự án thiếu tài liệu dành cho người dùng cuối. Meshery là một bình diện quản lý dịch vụ với tính năng đo điểm chuẩn hiệu suất cho tất cả các loại dịch vụ hỗ trợ việc áp dụng, định cấu hình, vận hành và quản lý hiệu suất của các lưới dịch vụ khác nhau, đồng thời kết 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 về 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 dành cho người dùng: Trong số các nền tảng SMI hiện có: Ứng dụng mẫu, Learn Layer5 (Lớp 5), 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 của SMI. Tuy nhiên, các dự án SMI hoàn toàn thiếu hướng dẫn cho người dùng cuối. Đây là một trở ngại nghiêm trọng do tính chất kỹ thuật cao của các dự án. Meshery là ứng dụng hoàn hảo để giới thiệu các lợi ích và cách sử dụng SMI cũng như các mạng dịch vụ có liên quan. Đó là lý do tôi sẽ sử dụng ứng dụng này làm công cụ cơ bản để giới thiệu các tính năng của SMI.

Tài liệu API: Hiện không có. SMI và nhiều dự án liên quan có cá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/meshery/blob/master/router/server.go), nhưng các điểm cuối này không được chú thích hoặc ghi lại bên ngoài. Bạn có thể giải quyết vấn đề này bằng cách cung cấp tài liệu có ý nghĩa về API và có thể cải thiện bằng cách thêm các cách để người dùng kiểm thử đ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 sử dụng được tạo để cho phép người dùng tham gia và chạy thử Phần mềm. Các tính năng này cần có tính tương tác và thẩm mỹ để thu hút sự chú ý của người dùng, đồng thời quan trọng nhất là phải dễ sử dụng.

Tuy nhiên, để viết hoặc lưu trữ Hướng dẫn người dùng, bạn nên sử dụng định dạng dành cho người lớn hơn vì Hướng dẫn người dùng thường đóng vai trò là hướng dẫn tham khảo hoặc là nơi để khắc phục nhanh sự cố. Thay vì có tính tương tác, các trang này cần được sắp xếp hợp lý và tập trung vào việc cải thiện tính rõ ràng, tính nhất quán và luồng người dùng hiệu quả.

Giải pháp khả thi cho vấn đề này là tạo các hướng dẫn Người dùng riêng biệt bằng các Lớp học lập trình của Google và một Hướng dẫn sử dụng độc lập với sự trợ giúp của Jekyll. Cuối cùng, bạn có thể tích hợp các hướng dẫn này với tài liệu về API để mang lại 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: 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 trong đó. Dịch vụ này phục vụ cả cá nhân và tổ chức.

Hướng dẫn người dùng: Tôi sẽ nhắm đến người dùng mới bắt đầu, không giả định người dùng có kiến thức CNTT sẵn có. Mục tiêu: Người dùng mới bắt đầu Lý do: Được dùng chủ yếu làm hướng dẫn tham khảo lớn và cần được cập nhật theo thời gian. Tài liệu này sẽ bao gồm các nội dung giải thích chuyên sâu và các mẹo hữu ích để đảm bảo rằng 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 một mạng dịch vụ. Hướng dẫn sẽ trở nên hấp dẫ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, 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 sẽ là làm cho hướng dẫn trở nên hấp dẫn và bắt mắt để giữ sự chú ý của người dùng và cho phép chạy thử nghiệm phần mềm một cách suôn sẻ, từ đó giúp người dùng hiểu rõ hơn về Giao diện lưới dịch vụ.

Tài liệu về Điểm 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 mạng dịch vụ, phù hợp hơn với người dùng nâng cao có kiến thức cơ bản về CNTT. Người dùng nâng cao sẽ tìm kiếm các hướng dẫn ngắn gọn, cũng có thể 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 phù hợp để có thể 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 của tài liệu đó. Tốt nhất là bạn nên tự động hoá quy trình này.

Tài nguyên: Hướng dẫn người dùng: Lớp học lập trình dành cho nhà phát triển của Google – Dùng để tạo các hướng dẫn toàn diện và có tính tương tác 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 thực hành. – Được 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. Tạo ra các hướng dẫn bắt 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ể nâng cao và dễ dàng triển khai các lớp học lập trình của Google bằng cách sử dụng dự án CLaaT (Lớp học lập trình dưới dạng một thực thể). Đây là một chương trình cung cấp công cụ dòng lệnh dùng để chuyển đổi các hướng dẫn được viết trong Google Tài liệu bằng Markdown sang đị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ó cho meshery.io, có thể tìm thấy tại đây, được lưu trữ trên Jekyll và sử dụng giao diện Docsy Jekyll. Công cụ này sử dụng Markdown, liquid, HTML và CSS để tạo các trang web tĩnh, sẵn sàng lưu trữ và chạy trên môi trường phát triển Ruby. Lợi ích: – Có thể lưu trữ trang web ngay trong kho lưu trữ GitHub. – Đây là một Dự án được hỗ trợ tốt với cộng đồng rất tích cực – Bạn có thể 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 hiện có về SMI và Meshery mà không phải bận tâm về việc di chuyển sang một nền tảng khác.

Tài liệu API: Swagger (hoặc Swaggo) sẽ được dùng để tạo tài liệu API cho SMI và Meshery. Đây là một giải pháp thanh lịch để 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 của bạn 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ó 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 của 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 mạng 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 cho người dùng cuối, sử dụng Jekyll cho lưới dịch vụ. – Sử dụng Swagger để tạo tài liệu về điểm cuối API cho SMI. – Xây dựng cộng đồng dự án để 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 đóng góp nội dung dưới sự hướng dẫn và kiểm duyệt của cộng đồng SMI.

Tiến trình đề xuất có tại đây: https://docs.google.com/document/d/1If2mtBdWZer4qrh66NfXOWBx_3-tiA09jnoPMqy2lqs/edit#bookmark=kix.j1b6m64eubsl

Cấu trúc: Bạn có thể xem 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 lại có dự án này? Cộng đồng mạng lưới dịch vụ đang mở rộng với tốc độ cực nhanh, nhờ được tích hợp gần đây dưới dạng một dự án hộp cát vào CNCF. Tuy nhiên, dự án này đang thiếu nghiêm trọng tài liệu, cả đối với người dùng cuối và nhà phát triển. Trước đây, tôi đã thử nghiệm nhiều loại lưới dịch vụ, trong đó có ứng dụng linksD với ứng dụng EmojiVoto, Istio với ứng dụng Bookinfo và Consul của Hashicorp. Tôi cũng đã thử tính năng phân chia 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 rất thú vị nhưng lại mang tính kỹ thuật cao và có thể khiến người dùng mới cũng như nhà phát triển muốn bắt đầu bước đầu tiên vào cộng đồng mạng lưới dịch vụ hoặc sử dụng mạ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, điều này chỉ có thể thực hiện được bằng các hướng dẫn và hướng dẫn hiệu quả và được ghi chép cẩn thận.