В Медузе мы стремимся предоставить разработчикам лучший опыт. Документация играет в этом огромную роль, поскольку она направляет разработчиков в их путешествии с программным обеспечением под рукой.

Как технический писатель в Medusa, я активно участвую в разработке нашей документации, особенно в написании контента. В течение 2022 года наша команда по документации приложила немало усилий, чтобы не только вкладывать больше ресурсов в документацию, но и искать различные способы ее улучшения.

В этой статье я поделюсь с вами тем, как мы улучшали нашу документацию в Medusa.

Что такое Медуза

Прежде чем погрузиться в улучшение нашей документации, важно знать, что такое Medusa и как ее используют разработчики.

Медуза — компонуемая коммерческая платформа с открытым исходным кодом. Его архитектура состоит из трех основных компонентов:

  • Сервер: безголовый бэкэнд, который обрабатывает всю бизнес-логику и данные, связанные с магазином электронной коммерции. Его можно подключить к любому интерфейсу как для витрины, так и для администратора.
  • Витрина: это интерфейс, который покупатели используют для просмотра интернет-магазина и совершения покупки. Мы предоставляем стартовые витрины Next.js и Gatsby, но разработчики могут создавать свои собственные, подключаясь к REST API витрины.
  • Администратор: это интерфейс, который продавцы используют для управления настройками и данными своего интернет-магазина. Мы предоставляем администратора Medusa, который предоставляет все необходимые и расширенные функции, но разработчики могут создавать свои собственные, подключаясь к REST API администратора.

Подробнее о возможностях и архитектуре Medusa можно узнать в документации.

Почему мы решили улучшить нашу документацию

В начале 2022 года наша документация предоставила разработчикам основную информацию, необходимую для запуска Medusa. Хотя этого было достаточно, чтобы они начали, этого было недостаточно, чтобы провести их через весь процесс разработки интернет-магазина.

Требовались улучшения в отношении содержания, дизайна, собранных отзывов и многого другого. Чтобы обеспечить эти улучшения, нам нужно было изменить то, как мы обрабатываем нашу документацию, и добавить больше ресурсов для ее разработки.

Как мы улучшали документацию

Просмотрите документацию как продукт

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

Мы в Medusa рано поняли, что документация — это то, что может способствовать дальнейшему внедрению Medusa.

Любознательным разработчикам будет достаточно руководства quickstart. Однако тем, кто действительно хочет использовать Medusa для создания магазина электронной коммерции для себя или своих клиентов, требуется документация, объясняющая различные концепции и способы их реализации.

Осознав, что документация является продуктом, мы смогли:

  • Распознайте приоритеты в отношении того, какие изменения/дополнения следует внести в документацию. Эти приоритеты могут быть определены на основе целей компании, нашей дорожной карты, улучшений пользовательского опыта и многого другого.
  • Планируйте нашу работу циклами. Теперь мы используем Линейный для управления циклами документации, задачами и невыполненными работами.
  • Привлекайте команду разработчиков и другие команды для дальнейшего улучшения нашей документации и опыта, который мы предоставляем.
  • Будьте более синхронизированы с основной командой разработчиков, чтобы вносить изменения в документацию вместе с изменениями в продукте. Основная команда инженеров также использует Linear, поэтому обе команды могут быть проинформированы о работе, которую они выполняют, что позволяет нам оставаться в синхронизации.

Рефакторинг нашего справочника по API

Наш предыдущий справочник по API нуждался в серьезных улучшениях, связанных с:

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

Чтобы улучшить его, мы решили, что его необходимо полностью реорганизовать, как в том, как он создавался, так и в том, как создавался сам веб-сайт.

Спецификация OpenAPI Справочник по API теперь создается с каждым новым выпуском, гарантируя, что она никогда не устареет. Мы также добавили в комментарии OpenAPI Spec в наш код (которые используются для создания справочника по API) примеры выполнения запросов с помощью клиента Medusa JS и cURL. Кроме того, мы добавили примеры ожидаемых параметров запроса или ответа и возможных ошибок.

Веб-сайт ранее был создан с помощью Gatsby с использованием пользовательской темы. В рамках рефакторинга мы изменили его, чтобы он работал как часть нашей основной документации Docusaurus и поверх Redocly с использованием плагина Redocusaurus.

Это позволило нам использовать функциональные возможности и функции Redocly, адаптированные для создания ссылок на API. Это еще больше улучшает опыт разработчиков.

Полностью переработана документация

В последнем квартале 2022 года мы сосредоточились на переработке документации, чтобы:

  • Улучшите взаимодействие пользователей и разработчиков с нашей документацией.
  • Реструктурируйте домашнюю страницу, чтобы направлять разработчиков к основным концепциям и руководствам в Medusa.
  • Предоставьте дизайн, который соответствует нашему фирменному стилю.

Благодаря нашей команде дизайнеров мы смогли представить чистый дизайн, краткую домашнюю страницу с необходимой документацией по использованию Medusa и улучшить существующие компоненты, используемые в документации.

Собирайте отзывы пользователей

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

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

Это помогло нам найти ошибки в документации, которые мы пропустили, или возможности сделать документацию более понятной.

Кроме того, для каждого блока кода мы добавили кнопку отчета. Это позволяет разработчикам быстро создать задачу на GitHub с информацией о проблеме, с которой они столкнулись при использовании этого блока кода.

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

Интеграция Vale и ESLint в документацию

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

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

Подобно тому, как программное обеспечение имеет интеграционные или модульные тесты, которые созданы для того, чтобы изменения в программном обеспечении не нарушали работу всей системы, мы реализовали тесты для руководства по стилю нашей документации, используя Vale и ESLint.

Vale позволяет вам определить набор правил для текстового содержимого вашей документации. Затем, при запуске файлов документации (например, файлов Markdown), он показывает вам любые ошибки в содержимом на основе ваших правил.

ESLint позволяет проверять наличие ошибок и применять стиль программирования для JavaScript. С помощью плагинов его можно интегрировать с другими языками и форматами. С помощью плагина eslint-plugin-markdown мы смогли проверить наличие ошибок и несоответствий в блоках кода внутри документации.

Мы также интегрировали оба инструмента в наш конвейер документации, обеспечив выполнение их тестов при каждом запросе на получение документации (PR) в нашем репозитории GitHub.

Запустите пользовательские пробные версии

Сбор отзывов пользователей полезен. Однако, чтобы обеспечить хороший опыт разработчиков, вам необходимо узнать, как ваши разработчики на самом деле используют вашу документацию.

Лучший способ сделать это — отслеживать их использование во время выполнения задачи. Для этого мы запустили пользовательские испытания нашей документации. Каждый квартал мы будем запускать пользовательскую пробную версию, посвященную определенной задаче, и отслеживать, как участники выполняют эту задачу.

Это важно, когда вы добавляете новую функцию в свою документацию и хотите посмотреть, как ее используют разработчики. Действительно ли это хорошая функция? Какие улучшения необходимы, чтобы сделать его лучше?

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

Если вы заинтересованы в том, чтобы помочь нам улучшить нашу документацию, узнайте больше о наших пробных версиях для пользователей и о том, как вы можете стать участником.

Что дальше?

Написание этой статьи не означает, что у нас есть лучшая документация, и путь к улучшению нашей документации на этом не заканчивается. Это непрерывный процесс и сотрудничество между нашими различными командами и сообществом Medusa. Цель состоит в том, чтобы убедиться, что мы понимаем наших разработчиков и делаем необходимую им информацию доступной.

Что вы думаете о наших улучшениях в документации? И есть ли у вас предложения по дальнейшим улучшениям? Дайте нам знать ниже!

Если у вас есть какие-либо проблемы или вопросы, связанные с Медузой, не стесняйтесь обращаться к команде Медузы через Discord.