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ở:
- Nền tảng điện toán gốc của đám mây (CNCF)
- Tác giả kỹ thuật:
- Syam Sundar K
- Tên dự án:
- Nhiều ví dụ tốt hơn về Kubectl
- Thời lượng dự án:
- Thời hạn tiêu chuẩn (3 tháng)
Mô tả dự án
Động lực của dự án này là nhằm cải thiện bản tóm tắt về kubectl và tài liệu tham khảo hiện có.
Đây là mục tiêu sau cùng của dự án này: • Tạo thêm nhiều ví dụ về kubectl hay hơn. • Thêm các ví dụ về kubectl vào bảng nhớ nhanh về kubectl. • Tái cấu trúc tài liệu kubectl để tăng mức độ hữu ích tối đa.
Mục tiêu I – Ví dụ về kubectl:
Sẽ làm việc chặt chẽ với các nhóm quan tâm đặc biệt về CLI để nắm được bối cảnh, loại ví dụ mà người dùng kubernetes muốn nhất và ghi lại ví dụ đó. Chẳng hạn như cải thiện các lệnh kubectl hiện có trên bản tóm tắt cho đến thêm các lệnh mới vào bản tóm tắt.
Mục tiêu II – Tăng mức độ hữu ích của tài liệu:
Để tăng tính hữu ích của tài liệu, bạn có thể làm như sau:
• Loại bỏ khó khăn cho người mới bắt đầu • Sắp xếp lại lệnh kubectl theo thứ tự nhất định để đảm bảo tính liên tục trong luồng logic
Loại bỏ những khó khăn của người mới bắt đầu thông qua nội dung giải thích tốt hơn về lệnh / trường hợp sử dụng. Điều này có vẻ đơn giản nhưng có thể ảnh hưởng đáng kể đến việc người mới bắt đầu tiếp tục hay bỏ dở việc học. Ví dụ: khi bắt đầu sử dụng kubernetes thông qua kubectl, tôi không chắc chắn về sự khác biệt giữa các vùng chứa và bản triển khai. Ban đầu, tôi đã triển khai một dịch vụ phụ trợ được viết bằng nodejs. Sau vài giờ, tôi muốn tắt ứng dụng này nên đã thử xoá pod, nhưng do bản chất tự phục hồi của các pod nên chúng đã được tạo lại. Tôi hơi bối rối về những gì đang diễn ra và thắc mắc tại sao trang này lại được tạo lại chứ không bị xoá. Sau vài lần tra cứu trên web, tôi nhận thấy việc xoá các nhóm không giống với việc xoá một bản triển khai. Đối với những người có kinh nghiệm, điều này có vẻ đơn giản, nhưng một nội dung giải thích rõ ràng giúp loại bỏ những loại sự mơ hồ này là yếu tố phân biệt tài liệu tốt với tài liệu tuyệt vời.
Sắp xếp lại lệnh kubectl theo một thứ tự nhất định để đảm bảo tính liên tục trong luồng logic. Nếu là người tin tưởng mạnh mẽ vào việc kể chuyện như tôi, có thể bạn sẽ thắc mắc làm cách nào để đưa các thành phần kể chuyện vào một trang tính có danh sách các lệnh dòng lệnh. Tôi xin trả lời rằng bạn có thể làm được điều đó. Mọi thứ chúng ta học đều có một luồng logic – một điểm bắt đầu và một điểm kết thúc, nếu bạn muốn. Kubectl là một công cụ dòng lệnh, rõ ràng là có độ dốc học tập, thực tế là độ dốc học tập này trùng khớp với độ dốc học tập của chính Kubernetes. Vì hầu hết mọi người đều bắt đầu hành trình với kubernetes thông qua kubectl (ngoại trừ những người sử dụng giao diện người dùng web) và vì độ dốc học tập của kubectl gắn chặt với độ dốc học tập của kubernetes, nên bạn có thể cải thiện đáng kể tài liệu chỉ bằng cách thay đổi thứ tự của các lệnh này và giới thiệu các thành phần kể chuyện vào tài liệu. Ví dụ: bạn có thể giải thích các tính năng như tự động điều chỉnh kích thước theo chiều ngang của nhóm sau khi giải thích tài nguyên bằng các ví dụ và hình minh hoạ thực tế.
Mục tiêu III – Cải thiện khả năng hữu dụng của Tài liệu:
Gần đây, việc di chuyển trang web của Kubernetes sang Docsy Hugo rất tuyệt vời và đây là một bước thay đổi lớn trong lĩnh vực tài liệu. Mặc dù quá trình di chuyển đã thành công, nhưng không gian tài liệu vẫn còn nhiều điểm cần cải thiện.
Sau đây là một số thay đổi mà tôi đề xuất:
• Ngăn bên trái tự động di chuyển đến phần hiện đang hoạt động trên tài liệu chính – Tính năng này có thể giúp bạn theo dõi các phần hiện tại, sắp tới và trước đây. • Sao chép vào bảng nhớ tạm – một số lệnh có thể dài, chức năng sao chép có thể hữu ích khi làm việc với những loại lệnh này. • Định dạng nội dung của tệp doc – Sau khi di chuyển, nội dung trong một số trang không được định dạng đúng cách. Ví dụ: mục Loại tài nguyên trong phần tổng quan về kubectl. Điều này làm giảm trải nghiệm người dùng.
Đây là những thay đổi có thể nâng cao trải nghiệm người dùng trên trang web của kubernetes và cũng có thể giúp tăng năng suất của người dùng.