На этой странице содержится подробная информация о проекте технического написания, принятом для участия в Google Season of Docs.
Краткое описание проекта
- Организация с открытым исходным кодом:
- Фонд облачных вычислений (CNCF)
- Технический писатель:
- Сьям Сундар К.
- Название проекта:
- Больше и лучше примеров Kubectl
- Длина проекта:
- Стандартная продолжительность (3 месяца)
Описание Проекта
Целью этого проекта будет улучшение существующей шпаргалки и справочной документации kubectl.
Вот конечные цели этого проекта: • Создавать больше и лучше примеров kubectl. • Добавьте примеры kubectl в шпаргалку kubectl. • Выполните рефакторинг документации kubectl для обеспечения максимальной полезности.
Цель I. Примеры для kubectl:
Мы будем тесно сотрудничать с группами особых интересов CLI, чтобы понять контекст, какие примеры нужны пользователям Kubernetes больше всего, и документировать это. Это может варьироваться от улучшения существующих команд kubectl в шпаргалке до добавления в шпаргалку новых команд.
Цель II – повышение полезности документов:
Чтобы повысить полезность документации, можно сделать следующее:
• Устранение проблем новичков. • Перестановка команды kubectl в определенном порядке, чтобы обеспечить непрерывность логического потока.
Устраните затруднения новичков за счет лучшего объяснения команд/пользователей. Это может показаться простым, но может существенно повлиять на новичков, заставивших их продолжить или прекратить обучение. Скажем, например, когда я начал работать с kubernetes через kubectl, я не был уверен в различиях между модулями и развертываниями. Первоначально я развернул серверную службу, написанную на nodejs. Через несколько часов мне захотелось его отключить, поэтому я попытался удалить модуль, но из-за самовосстанавливающейся природы модулей они были созданы снова. Я был немного озадачен происходящим, и мне было интересно, почему это воссоздается, а не удаляется. После нескольких поисков в Интернете я понял, что удаление модулей — это не то же самое, что удаление развертывания. Для тренированного глаза это может показаться простым, но четкое объяснение, устраняющее подобные двусмысленности, — это то, что отличает хорошего документа от великого.
Перестановка команды kubectl в определенном порядке для обеспечения непрерывности логического потока. Если вы, как и я, твердо верите в повествование, вам, вероятно, будет интересно, как перенести элементы повествования в документацию, в которой есть список команд терминала, я говорю, это можно сделать. Все, чему мы учимся, всегда имеет логическую последовательность — начальную и конечную точку, если хотите. Kubectl как инструмент командной строки, очевидно, имеет кривую обучения, фактически ее кривая обучения совпадает с кривой обучения самого Kubernetes. Поскольку почти каждый начинает свой путь с kubernetes через kubectl (кроме тех, кто использует веб-интерфейс) и поскольку кривая обучения тесно связана с кривой обучения kubernetes, документацию можно значительно улучшить, просто изменив порядок этих команд и привнесение в него элементов повествования. Скажем, например, такие функции, как горизонтальное автоматическое масштабирование модулей, можно объяснить после объяснения ресурсов с примерами и иллюстрациями из реальной жизни.
Цель 3. Улучшение удобства использования Документов.
Недавний перенос веб-сайта Kubernetes на Docsy Hugo впечатляет и представляет собой огромный сдвиг в точки зрения документации. Хотя миграция прошла успешно, в области документации еще есть место для многих улучшений.
Вот некоторые изменения, которые я бы предложил:
• Автоматическая прокрутка левой панели к текущему активному разделу основных документов. Это может быть полезно для отслеживания текущих, предстоящих и прошлых разделов. • Копировать в буфер обмена — некоторые команды могут быть длинными, функция копирования может оказаться полезной при работе с такими командами. • Форматирование содержимого файлов документов. После миграции содержимое некоторых страниц не форматируется должным образом. например: раздел «Тип ресурса» в обзоре kubectl. Это ухудшает пользовательский опыт.
Это изменения, которые могут улучшить взаимодействие с пользователем на веб-сайте Kubernetes, а также повысить производительность пользователей.