Как мы создавали документацию по нашему программному обеспечению на Docusaurus

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

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

Выявление проблем с нашим процессом документации

Когда мы впервые запустили Courier, нам нужна была [документация] (https://www.courier.com/docs/), объясняющая, как использовать Courier как продукт. Итак, мы нашли инструмент, который может помочь в этом: ReadMe.

ReadMe дал нам достаточно возможностей, чтобы начать работу с нашей документацией. Мы могли создавать и обновлять нашу документацию по мере необходимости и без особых усилий, но мы не могли сотрудничать столько, сколько нам нужно, и могли сохранять только один черновик за раз. Это было серьезной проблемой, потому что любой мог легко перезаписать чужую работу, если он работал над одним и тем же файлом в одно и то же время. ReadMe также имел плоскую файловую структуру, которую было неудобно использовать. Также не было реальной интеграции [Git] (https://git-scm.com/) в их интерфейс командной строки, поэтому у нас были проблемы с управлением версиями документов и совместной работой. В конечном счете, это означало, что документы находились в процессе утверждения в течение неоправданно долгого времени, и не все могли внести предложения по улучшению по мере их поступления.

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

Предпосылки для инструмента документирования

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

Безграничное сотрудничество

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

Управление версиями

Растущая компания приходит с неизбежностью растущего продукта. По мере выпуска новых версий продукта всегда будет время наложения, когда некоторые из наших пользователей используют более старую версию продукта, а некоторые — новейшую версию. Наша документация должна обслуживать обе эти группы пользователей, а это значит, что для того, чтобы у всех была правильная информация, управление версиями является важной функцией документации. Например, нам нужно хранить документацию для нашей версии API 1.0.0 отдельно от документации для API 2.0.0 и обеспечить возможность быстрого и легкого обновления и переключения между версиями.

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

Проверка ссылки

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

Локализация

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

Docusaurus соответствует нашему списку

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

С Docusaurus мы создавали наши документы как уценки и экспортировали их как статический сайт. Мы создали повторно используемые пользовательские компоненты и теперь имеем полный контроль над тем, как мы создаем нашу документацию. Интеграция MDX также особенно полезна, поскольку позволяет встраивать любой код JavaScript в файл .md.

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

Я также сам создал наш пользовательский обозреватель API, который позволяет разработчикам опробовать наши методы API непосредственно из нашей документации. Я построил его как встроенный компонент React, помещенный в файл MDX. Поскольку мы размещаем нашу документацию на Vercel, мы можем использовать Vercel Functions для проксирования запросов API Explorer к Courier API через конечную точку нашей внутренней документации.

С Docusaurus мы смогли быстро и легко создать нашу документацию. Теперь мы можем вносить обновления, просто клонируя репозиторий на GitHub, отделяя нашу основную ветку, внедряя изменения и создавая запрос на вытягивание (PR). После того, как кто-то просмотрел и одобрил PR, он объединяется с основной ветвью, которая развертывается в Vercel и обновляет наш сайт с изменениями.

Все, что нам нужно для внесения вклада в нашу документацию, — это учетная запись GitHub и интегрированная среда разработки (IDE). Это помогает нам отслеживать каждую задачу обслуживания нашей документации.

Что дальше с нашей документацией?

Есть еще несколько целей, которые у нас есть для нашей документации. Нам еще предстоит использовать функцию локализации Docusaurus, так что она находится в разработке. Мы также недавно сделали нашу документацию [с открытым исходным кодом] (https://github.com/trycourier/docs), чтобы приветствовать внешних участников. Таким образом, пользователь может взять на себя ответственность за обновления, которые он хочет, и помочь себе и другим, кто выиграет от их вклада.

А пока научитесь пользоваться Courier с помощью нашей [документации и руководств] (https://www.courier.com/docs/guides/tutorials/how-to-design-a-notification-template/). Мы также прямая трансляция контента, который поможет вам начать и продолжить работу с Courier .

Также опубликовано здесь