Как автоматизировать рабочий процесс документации для разработчиков

Чтобы получить максимальную отдачу от этого руководства, вы должны быть знакомы с Git, GitHub и Linux, а также с командной строкой.

Почему вы должны заботиться о высококачественной документации?

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

Плохая документация также ставит под угрозу хорошее обслуживание клиентов. По словам Джеффа Лоусона, автора Ask Your Developer и основателя Twilio, если вы продаете API как продукт, документация — это лучшая реклама для технических заинтересованных сторон . IBM провела исследование важности документации, и 90 % респондентов признали, что они принимали решения о покупке, основываясь на качестве документации продукта.

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

Если документация так важна, то почему инженерные группы лишают ее приоритета?

Написание документации может вывести разработчиков из «потока». Документация часто живет за пределами основной кодовой базы , и ее сложно найти и обновить. Помещение его в электронную таблицу Excel или проприетарную CMS не редкость.

Автоматизация документации и улучшение рабочего процесса документации исправляют это.

Автоматизация документирования на высоком уровне

Что означает автоматизация документации? Это означает принятие общих методов разработки программного обеспечения. Когда вы автоматизируете документацию, вы:

• написание вашей документации в Markdown;
• использование конвейера непрерывной интеграции и непрерывного развертывания (CI/CD) для выполнения таких задач, как исправление ошибок и развертывание обновлений (в этом руководстве мы собираемся выделить действия GitHub);
• внедрение таких инструментов, как Vale, для обеспечения соблюдения руководства по стилю и исправления распространенных грамматических ошибок.

Руководства по стилю

Прежде чем использовать такие инструменты, как Vale и GitHub Actions, для автоматизации руководства по стилю, давайте на минутку определим, что такое руководство по стилю.

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

Когда вы испытываете это чувство, ваш голос и тон могут быть отключены . Уточнение голоса и тона — это способ сделать текст более связным, даже если вы разрабатываете документацию, отредактированную отделом контроля качества, инженерами и командой разработчиков. Ниже приведен пример руководства по стилю для приложения городского автобуса TAPP, взятого из книги « Стратегическое письмо для UX » Торри Подмайерски.

TAPP — это транзитное приложение (для автобусов и поездов). Заголовок таблицы объявляет ценности TAPP как компании, будучи эффективной, заслуживающей доверия и доступной. В левой части таблицы перечислены различные части, охватываемые руководством по стилю: понятия, словарный запас, многословие, грамматика и пунктуация.

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

Руководство по стилю технического письма

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

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

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

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

Линтеры и CI/CD для документации

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

Использование некоторой автоматизации документации наряду с линтером является обычным явлением. Когда мы говорим об автоматизации в этом контексте, мы имеем в виду рабочий процесс непрерывной интеграции и непрерывного развертывания (CI/CD). CI автоматизирует создание и тестирование документации . CD автоматизирует выпуск кода.

Вы можете использовать множество различных типов приложений для реализации рабочего процесса CI/CD. В этом руководстве мы собираемся использовать GitHub Actions для запуска нашего линтера документации. Действия GitHub запускают CI непосредственно в репозитории GitHub, поэтому нет необходимости использовать стороннее приложение, например CircleCI или Travis.

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

Действия на GitHub

Сначала создайте репозиторий GitHub. Затем локально создайте папку и cd в нее.

 mkdir automated-docs cd automated-docs

Как только вы окажетесь в папке, инициализируйте каталог для Git.

 git init

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

 mkdir .github/ && cd .github/ && mkdir workflows/ && cd workflows/

Рабочие процессы — это место, где мы будем хранить все наши действия GitHub. Создав папку workflows , создайте новый рабочий процесс. Мы собираемся назвать этот рабочий процесс vale.yml .

 touch vale.yml

Vale.yml — это файл YAML. В этот файл рабочего процесса мы включим действия и задания.

Теперь откройте vale.yml в своем любимом текстовом редакторе.

 nano vale.yml

Скопируйте и вставьте следующее в vale.yml , и давайте рассмотрим контекст и синтаксис.

 # This is a basic workflow to help you get started with Actions name: CI # Controls when the workflow will run on: # Triggers the workflow on push or pull request events but only for the main branch push: branches: [ main ] pull_request: branches: [ main ] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: # A workflow run is made up of one or more jobs that can run sequentially or in parallel jobs: # This workflow contains a single job called "build" build: # The type of runner that the job will run on runs-on: ubuntu-latest # Steps represent a sequence of tasks that will be executed as part of the job steps: # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it - uses: actions/checkout@v2 # Runs a single command using the runners shell - name: Run a one-line script run: echo Hello, world! # Runs a set of commands using the runners shell - name: Run a multi-line script run: | echo Add other actions to build, echo test, and deploy your project. env: GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

• name
  Это имя, или то, что мы называем нашим рабочим процессом. Это строка.
• on
  Это контролирует рабочий процесс и триггеры.
• jobs
  Здесь мы настраиваем и контролируем наши действия. Мы выбираем среду, в которой будут выполняться наши действия — обычно лучше использовать Ubuntu. И здесь мы добавим наши действия.

На GitHub есть руководство по всему остальному синтаксису и переменным рабочего процесса, если вам интересно.

В этом разделе у нас есть:

• узнал, что такое действия GitHub,
• создал наш первый рабочий процесс GitHub,
• определили наиболее важные части файла YAML рабочего процесса GitHub.

Далее мы настроим рабочий процесс GitHub для использования Vale.

Настройка Vale в файле действий GitHub

После того, как мы скопировали базовый файл рабочего процесса, пришло время настроить его, чтобы мы могли начать использовать действия Vale. Первое, что нужно сделать, это изменить имя файла YAML на Docs-Linting .

 # This is a basic workflow to help you get started with Actions. name: Docs-Linting

Затем мы хотим запустить тест Vale после того, как кто-то отправит свои изменения в основную ветку на GitHub. Мы не хотим, чтобы тест запускался, когда кто-то создает запрос на вытягивание, поэтому мы удалим эту часть файла YAML.

 on: # Triggers the workflow on push or pull request events but only for the main branch push: branches: [ main ]

Раздел jobs является основной частью файла рабочего процесса и отвечает за выполнение действий GitHub.

 jobs: build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@master

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

Теперь пришло время добавить действие Vale в наш рабочий процесс GitHub.

 - name: Vale uses: errata-ai/[email protected] with: debug: true styles: | https://github.com/errata-ai/write-good/releases/latest/download/write-good.zip https://github.com/errata-ai/Microsoft/releases/latest/download/Microsoft.zip env: GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

Мы назвали наше действие Vale . Переменная uses показывает, какую версию Vale мы собираемся реализовать — в идеале мы должны использовать самую последнюю версию. В переменной with мы устанавливаем для debug значение true .

Раздел styles дает нам возможность добавить руководство по стилю в Vale. В этом примере мы собираемся использовать write-good и официальное руководство по стилю Microsoft. Имейте в виду, что мы можем использовать и другие руководства по стилю.

Заключительная часть этого действия GitHub — env . Чтобы запустить это действие GitHub, нам нужно включить секретный токен.

Вот как должен выглядеть результат:

 # This is a basic workflow to help you get started with Actions. name: Docs-Linting # Controls when the action will run. on: # Triggers the workflow on push or pull request events but only for the main branch push: branches: [ main ] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: jobs: prose: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@master - name: Vale uses: errata-ai/[email protected] with: debug: true styles: | https://github.com/errata-ai/write-good/releases/latest/download/write-good.zip https://github.com/errata-ai/Microsoft/releases/latest/download/Microsoft.zip env: GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

Когда вы закончите вносить изменения, сохраните файл, зафиксируйте его в Git и отправьте изменения на GitHub.

 git add .github/workflows/vale.yml git commit -m "Added github repo to project" git push -u origin main

Напомним, в этом разделе у нас есть:

• запускает действие, которое происходит, когда мы отправляем новый код в main ветку;
• добавлено действие Vale, устанавливающее для debug значение true и идентифицирующее руководства по стилю;
• добавлен токен GitHub;
• зафиксировали изменения и отправили на GitHub.

В следующем разделе мы собираемся создать файл конфигурации Vale.

Настройка файла конфигурации Vale

Перейдите в корень каталога вашего проекта и touch .vale.ini . Откройте .vale.ini в текстовом редакторе. Скопируйте и вставьте в .vale.ini следующее:

 StylesPath = .github/styles MinAlertLevel = warning [formats] Markdown = markdown [*.md] BasedOnStyles = write-good, Microsoft

• StylesPath = .github/styles
StylesPath указывает путь к стилям Vale.
• MinAlertLevel = warning
  Минимальный уровень предупреждения показывает шкалу серьезности предупреждений. Возможные варианты: suggestion , warning и error .
• [formats]
Markdown = markdown устанавливает формат как Markdown.
• [*.md]
  Конфигурация BasedOnStyles = write-good, Microsoft будет запускать write-good и руководство по стилю Microsoft для всех файлов Markdown, оканчивающихся на .md .

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

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

 git add .vale.ini git commit -m "Added Vale config file" git push -u origin main

В этой части мы изучили внутренности конфигурационного файла Vale. Теперь пришло время создать образец документации.

Создание документации и запуск действий Vale GitHub

Теперь пришло время увидеть действия Vale и GitHub в действии! Мы собираемся создать файл Markdown и заполнить его текстом. И мы собираемся получить наш текст от DeLorean Ipsum.

Перейдите в корень вашего проекта, а затем touch getting-started.md . Создав файл для getting-started работы, перейдите в DeLorean Ipsum и создайте фиктивный текст для своей документации. Затем вернитесь в текстовый редактор и вставьте текст в файл getting-started-md .

 # Getting Started Guide I can't play. It's my dad. They're late. My experiment worked. They're all exactly twenty-five minutes slow. Marty, this may seem a little foreward, but I was wondering if you would ask me to the Enchantment Under The Sea Dance on Saturday. Well, they're your parents, you must know them. What are their common interests, what do they like to do together? Okay. Are you okay? Whoa, wait, Doc. What, well you mean like a date? I don't wanna see you in here again. No, Biff, you leave her alone. Jesus, George, it's a wonder I was ever born. Hey, hey, keep rolling, keep rolling there. No, no, no, no, this sucker's electrical. But I need a nuclear reaction to generate the one point twenty-one gigawatts of electricity that I need. I swiped it from the old lady's liquor cabinet. You know Marty, you look so familiar, do I know your mother?

Сохраните файл, зафиксируйте его и отправьте на GitHub.

 git add getting-started.md git commit -m "first draft" git push -u origin main

После внесения изменений перейдите на GitHub, где находится ваш репозиторий. Перейдите на вкладку Actions .

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

Когда мы отправим документацию на GitHub, мы инициируем действие.

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

Нажмите «Добавленные документы», чтобы получить полный отчет.

Вы увидите, что мы получили 11 предупреждений. Разберемся с предупреждением о «ласковом слове». Вернитесь в текстовый редактор, откройте getting-started.md -started.md и удалите слово «точно».

 # Getting Started Guide I can't play. It's my dad. They're late. My experiment worked. They're all twenty-five minutes slow. Marty, this may seem a little foreward, but I was wondering if you would ask me to the Enchantment Under The Sea Dance on Saturday. Well, they're your parents, you must know them. What are their common interests, what do they like to do together? Okay. Are you okay? Whoa, wait, Doc. What, well you mean like a date? I don't wanna see you in here again. No, Biff, you leave her alone. Jesus, George, it's a wonder I was ever born. Hey, hey, keep rolling, keep rolling there. No, no, no, no, this sucker's electrical. But I need a nuclear reaction to generate the one point twenty-one gigawatts of electricity that I need. I swiped it from the old lady's liquor cabinet. You know Marty, you look so familiar, do I know your mother?

Сохраните изменения, зафиксируйте их в Git и отправьте новую версию файла на GitHub. Это должно вызвать действие GitHub .

Если мы нажмем «Удалить слово ласка», мы увидим, что у нас сейчас всего 10 предупреждений, а предупреждение «слово ласка» исчезло. Ура!

Мы закончили, и мы покрыли много земли. В этом разделе у нас есть:

• добавлена ​​документация в наш репозиторий Vale GitHub Actions,
• инициировал действие Vale GitHub,
• исправил ошибку, допущенную Vale, и отправил изменение обратно на GitHub.

Заключение

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

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