Оставить заявку

Обработка документации как кода от Mastercard

обработка документации как кода от mastercard

Внимание!  Статья свободного перевода от Google, оригинал здесь
Этот пост является продолжением поста Кенни Чоу «Переосмысление нашей контентной стратегии» и посвящен тому, как технический писатель рассматривает документацию как код.

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

  • Системы контроля версий, такие как Subversion или Git, для совместной работы в команде и отслеживания изменений
  • Автоматизированные системы для создания и развертывания контента аналогично тому, как Jenkins используется для создания и развертывания кода


В какой-то степени эта концепция не нова. Существует долгая история некоторых аспектов документации, автоматически генерируемой из комментариев в исходном коде. Например:

  • Справочная документация по классам для Java может быть построена из комментариев исходного кода Java с использованием инструмента под названием Javadoc
  • Веб-API RESTful могут быть задокументированы с использованием спецификаций Swagger (OpenAPI) в .yaml
  • Файлы .json снабжены описаниями для предоставления полезной справочной информации.


Тем не менее, в последние годы произошел взрыв в использовании инструментов генератора статического сайта. Эти инструменты берут контент, написанный в удобочитаемом формате, таком как markdown или AsciiDoc, и генерируют набор HTML-страниц, которые могут быть размещены в Интернете как статический веб-сайт. Это дало техническим авторам альтернативный подход к таким инструментам, как Microsoft Word или Adobe FrameMaker.


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


Mastercard использует этот подход для публикации контента на Mastercard Developers . Ранее весь контент в Mastercard Developers хранился в системе управления контентом (CMS) и редактировался с помощью инструмента «Что вы видите, что вы получаете» (WYSIWYG), работающего в браузере. Это было хорошо для несложного контента, но расстраивает технических писателей, создающих и поддерживающих более подробный контент. Редактор в CMS иногда работал медленно через браузер, где было медленное интернет-соединение, что затрудняло написание и редактирование. Точно так же были ограничения на стиль контента, который мог быть произведен. Вместо того, чтобы продолжать «прикреплять» больше типов контента к CMS, команда разработчиков Mastercard приняла идею использования нового набора инструментов для обеспечения большей гибкости.


Несколько инструментов генератор статического сайта были оценены до того, как принято решение использовать Гюго (см Кенни Чоу пост для более подробной информации). Авторы Hugo позволяют создавать контент в любом текстовом редакторе, используя стандартный формат уценки в (наши авторские группы предпочитают Atom ) с материалами, хранящимися в репозиториях Azure Git. Затем конвейер Azure автоматически «создает» веб-контент из источника уценки и развертывает работающий сайт. Результат выглядит хорошо благодаря «теме», которую мы разработали, а выход Hugo соответствует остальным разработчикам Mastercard. Процесс написания и редактирования работает хорошо, поэтому технические писатели счастливы.


Скопировано на
практике


  • Содержимое в уценке можно быстро и легко редактировать в автономном режиме без задержки
  • Изменения могут быть зафиксированы и отправлены в Git в текстовом редакторе Atom.
  • Hugo может быть установлен и запущен локально, поэтому мы можем просматривать локальную версию контента сразу в любом браузере
  • Несколько технических писателей могут внести свой вклад в содержание, поскольку мы работаем в ветвях Git.
  • Использование веток Git также означает, что мы можем работать над будущими функциями в отдельной ветке, не рискуя перезаписать последнюю документацию
  • Правила могут быть применены к запросам извлечения, поэтому действующий сайт не может быть обновлен без одобрения со стороны коллег.
  • Черновые ветки автоматически создают версии контента для конкретной ветки и внедряются в нашу рабочую среду, поэтому мы можем делиться контентом с другими командами для проверки.
  • После подтверждения запроса на ветку master сайт создается и развертывается за несколько секунд.
  • С документацией, созданной с помощью Hugo, намного проще ориентироваться, поскольку мы можем разбить материал на большее количество более коротких страниц с полным оглавлением / меню слева
  • Легко увидеть заметки / предупреждения / советы могут быть добавлены путем добавления окна вызова
  • Приятно выглядящие диаграммы последовательности из UML могут быть созданы с помощью плагина русалки (подробности см. В публикации Пола Блэнда)
  • При сборке сайта легко найти неработающие ссылки, чтобы их можно было исправить перед развертыванием / публикацией.

Скопированное
резюме


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




Появились вопросы?

Вы можете задать любой вопрос на форуме Технических писателей или напишите нам

Рейтинг@Mail.ru