Эта страница переведена с помощью Cloud Translation API.

Проект Cloud Native Computing Foundation (CNCF)

На этой странице содержится подробная информация о проекте технического написания, принятом для участия в Google Season of Docs.

Краткое описание проекта

Организация с открытым исходным кодом:: Фонд облачных вычислений (CNCF)
Технический писатель:: Шрити
Название проекта:: Улучшить документацию SMI и связанных с ними сервисных сеток.
Длина проекта:: Стандартная продолжительность (3 месяца)

Описание Проекта

Технология Service Mesh по существу направлена на обеспечение ценности растущего числа сервисов, удовлетворяя все ваши потребности в безопасности, управлении и мониторинге. Интерфейс Service Mesh (SMI) определяет набор API-интерфейсов для наиболее распространенных случаев использования Service Mesh (политика трафика, телеметрия и переключение) и обеспечивает совместимость между Service Mesh, которые представляют собой выделенные уровни инфраструктуры для управления связью между сервисами в микросервисная среда. Стандартизация этих интерфейсов обеспечит улучшенное взаимодействие с конечными пользователями и, таким образом, является будущей целью SMI и связанных с ними сервисных сетей.

Текущее состояние:

Руководства пользователя: SMI — это относительно новый проект «песочницы», переданный в дар CNCF в апреле 2020 года. В результате в проекте отсутствует документация для конечного пользователя. Meshery — это плоскость управления сервисами с оценкой производительности для всех видов сервисов, облегчающая внедрение, настройку, эксплуатацию и управление производительностью различных сервисных сеток, а также включает сбор и отображение метрик из приложений, работающих поверх любой сервисной сетки. Поэтому я хотел бы начать с руководства по Meshery, которое послужит отправной точкой для всего сообщества пользователей SMI.

Учебные пособия для пользователей: Среди существующих платформ SMI: Пример приложения Learn Layer5 в настоящее время служит средством обучения для SMI и примером приложения для проверки спецификации SMI. Но в остальном в проектах SMI полностью отсутствуют учебные пособия для конечных пользователей, которые является серьезным препятствием из-за сугубо технического характера проектов. Meshery — идеальное приложение для демонстрации преимуществ и использования SMI и связанных с ним сервисных сеток, поэтому я буду использовать его в качестве базового инструмента для демонстрации возможностей SMI.

Документация API: на данный момент не существует. Конечные точки API SMI и различных связанных проектов определены на платформе; Например, конечные точки Meshery определены на сервере server.go (https://github.com/layer5io/meshery/blob/master/router/server.go), но они не имеют ни хороших комментариев, ни документации извне. Эту проблему можно решить с помощью подробной документации API и можно улучшить, добавив пользователям способы тестирования его конечных точек и предварительного просмотра его функций.

Анализ:

Учебные пособия для пользователей созданы для того, чтобы дать пользователю возможность опробовать Программное обеспечение и протестировать его. Они должны быть интерактивными и эстетически привлекательными, чтобы удерживать внимание пользователя, и, самое главное, простыми в использовании.

Однако для написания или размещения руководств пользователя рекомендуется использовать более зрелый формат, поскольку руководства пользователя часто служат справочным руководством или местом, где можно быстро устранить проблемы. Вместо того, чтобы быть интерактивными, они должны быть хорошо структурированы и направлены на повышение ясности, последовательности и хорошего пользовательского потока.

Возможным решением этой проблемы было бы создание отдельных руководств для пользователей с использованием Google Codelabs и независимого руководства пользователя с помощью Jekyll и, наконец, их интеграция вместе с документацией API, чтобы предоставить всесторонний опыт как конечному пользователю, так и будущим сотрудникам. .

Целевая аудитория: проекты SMI предоставляют методы развертывания и эксплуатации, среду обучения и контрольные показатели производительности для всех проектов, входящих в их состав. Он обслуживает как частных лиц, так и организации.

Руководства пользователя: я буду ориентироваться на начинающих пользователей, без каких-либо предположений о наличии у них уже существующих знаний в области ИТ. Цель: начинающие пользователи. Причина: используется в основном как обширное справочное руководство, которое со временем необходимо будет обновлять. Сюда будут включены подробные объяснения и полезные советы, которые помогут пользователю получить всю информацию, необходимую для настройки и работы с сервисной сеткой. Руководство станет более привлекательным и удобным для пользователя за счет добавления видео, изображений, снимков экрана и GIF-файлов, где это необходимо.

Учебники для пользователей: Цель: начинающие пользователи. Причина: основное внимание будет уделено тому, чтобы сделать обучающие материалы интересными и эстетически привлекательными, чтобы удерживать внимание пользователя и обеспечить плавный тестовый запуск программного обеспечения, что приведет к лучшему пониманию интерфейса Service Mesh.

Документация по конечным точкам API: Цель: опытные пользователи. Причина: в этом разделе основное внимание уделяется использованию более сложных функций сервисной сетки, что больше отвечает интересам опытных пользователей с базовым уровнем знаний в области ИТ. Опытным пользователям будут интересны краткие руководства, которые при необходимости можно использовать в качестве справочных руководств. Документация по Endpoint должна быть написана таким образом, чтобы ее можно было легко обновлять без ущерба для ее точности и последовательности. Желательно, чтобы это был автоматизированный процесс.

Ресурсы: Учебники для пользователей: Google Developers Codelab — используется для создания интерактивных и полных руководств для конечных пользователей. Преимущества: - Может создавать обучающие программы для песочницы. - Имеет практический подход. - Написано с использованием Google Docs и поддерживает текст Markdown. - Можно отслеживать с помощью Google Analytics. - Легко наблюдать за пользовательским трафиком. - Легко использовать. Создает эстетически приятные учебные пособия, которые позволяют пользователю напрямую работать с программным обеспечением без каких-либо прямых инвестиций.

Google Codelabs можно расширить и легко развернуть с помощью проекта CLaaT (Codelabs as a Thing). Это программа, предлагающая инструмент командной строки, используемый для преобразования учебных пособий, написанных в Google Doc, с использованием Markdown, в формат Codelabs (HTML).

Руководства пользователя: Jekyll — существующая документация для meshery.io, которую можно найти здесь, размещена на Jekyll и использует тему Docsy Jekyll. Он использует Markdown, Liquid, HTML и CSS для создания готовых к размещению статических веб-сайтов и работает в среде разработки Ruby. Преимущества: — Может размещать сайты непосредственно из репозиториев GitHub. - Это хорошо поддерживаемый проект с очень активным сообществом. Руководства пользователя и улучшения можно просто добавить в существующую документацию SMI и Meshery, не беспокоясь о переходе на другую платформу.

Документация API: Swagger (альтернативно Swaggo) будет использоваться для создания документации API для SMI и Meshery. Это элегантное решение для написания документов API. Преимущества: - Документация из вашего проекта API: гарантирует, что ваша документация будет актуальной по мере развития вашего API. - Документация на основе вашего проекта API: может быть создана автоматически на основе определений API. - Поддержка нескольких версий документации. - Индивидуальные конструкции API.

Цели проекта: - Используйте Google Developer Codelabs для создания интерактивных руководств для конечных пользователей по SMI и связанным с ними сервисным сеткам, используя Meshery в качестве инструмента. - Создайте руководство для конечного пользователя, используя Jekyll для сервисных сеток. — Используйте Swagger для создания документации по конечным точкам API для SMI. - Сделать сообщество проекта управляемым, чтобы будущие и нынешние пользователи или разработчики могли легко продолжать добавлять к нему дополнения под руководством и модерацией сообщества SMI.

Сроки: предлагаемый график можно найти здесь: https://docs.google.com/document/d/1If2mtBdWZer4qrh66NfXOWBx_3-tiA09jnoPMqy2lqs/edit#bookmark=kix.j1b6m64eubsl.

Структура. Предлагаемую структуру Руководства пользователя можно найти здесь: https://docs.google.com/document/d/1A3YYAMUTe06MojNWo8hdF4KZbvr-qVaaA2myzWeshHQ/edit?usp=sharing.

Почему этот проект? Сообщество Service Mesh расширяется молниеносными темпами, чему способствовала его недавняя интеграция в качестве проекта песочницы в CNCF. Однако в проекте наблюдается серьезная нехватка документации как для конечных пользователей, так и для разработчиков. В прошлом я экспериментировал с различными сервисными сетками, включая linkerD с приложением EmojiVoto, Istio с его приложением bookinfo и Consul от Hashicorp. Я также попробовал разделить трафик SMI и внедрил различные правила проверки в моей конфигурации Service Mesh. Процесс обучения увлекательный, но очень технический и может оттолкнуть как новых пользователей, так и разработчиков, желающих сделать свои первые шаги в сообществе сервисных сетей или использовать сервисные сетки для своих личных или профессиональных проектов. Я хотел бы восполнить этот пробел, что можно сделать только с помощью эффективных и хорошо документированных руководств и учебных пособий.