Como automatizar o fluxo de trabalho de documentação para desenvolvedores

Para tirar o máximo proveito deste tutorial, você deve estar familiarizado com: Git, GitHub e Linux e a linha de comando.

Por que você deve se preocupar com a documentação de alta qualidade?

Muitas equipes lutam para escrever a documentação . Quando você verifica uma estrutura, a documentação geralmente está desatualizada ou pouco clara. Isso pode levar à frustração interna quando um membro da equipe tenta adicionar um recurso, mas não entende como o recurso atual funciona devido à documentação ruim. Isso pode levar a horas improdutivas no trabalho.

A má documentação também compromete uma boa experiência do cliente. De acordo com Jeff Lawson, autor de Pergunte ao seu desenvolvedor e fundador do Twilio, se você está vendendo uma API como produto, a documentação é o melhor anúncio para os interessados ​​técnicos . A IBM fez um estudo sobre a importância da documentação e 90% dos entrevistados admitiram que tomaram suas decisões de compra com base na qualidade da documentação de um produto.

Escrever uma boa documentação é importante para as experiências do desenvolvedor e do cliente.

Se a documentação é tão importante, então por que as equipes de engenharia a despriorizam?

Escrever documentação pode tirar os desenvolvedores do “fluxo”. A documentação geralmente fica fora da base de código principal , e é complicado encontrá-la e atualizá-la. Colocá-lo em uma planilha do Excel ou em um CMS proprietário não é incomum.

Automatizar a documentação e melhorar o fluxo de trabalho de documentação corrige isso.

Automatizando a documentação de alto nível

O que significa automatizar a documentação? Significa adotar práticas comuns de desenvolvimento de software. Ao automatizar a documentação, você está:

• escrever sua documentação no Markdown;
• usando um pipeline de integração contínua e implantação contínua (CI/CD) para executar tarefas como corrigir erros e implantar atualizações (neste tutorial, vamos destacar GitHub Actions);
• implementando ferramentas como a Vale para aplicar um guia de estilo e corrigir erros gramaticais comuns.

Os guias de estilo

Antes de usar ferramentas como Vale e GitHub Actions para automatizar o guia de estilo, vamos definir o que exatamente é um guia de estilo.

Sabe aquela sensação de quando você está escrevendo uma documentação e algo parece um pouco errado? Suas explicações não se encaixam no restante da documentação, mas você não consegue descrever por que elas estão erradas. A escrita explica o conceito, mas não parece se encaixar.

Quando você tem essa sensação, sua voz e tom podem estar desligados . Refinar a voz e o tom é uma maneira de tornar a escrita coesa, mesmo se você estiver desenvolvendo documentação que foi editada pelas equipes de controle de qualidade, engenharia e produto. Abaixo está um exemplo de guia de estilo do aplicativo de ônibus urbano TAPP, retirado do livro Strategic Writing for UX de Torrey Podmajersky.

TAPP é um aplicativo de trânsito (para ônibus e trens). O cabeçalho da tabela anuncia os valores da TAPP como empresa, sendo eficiente, confiável e acessível. O lado esquerdo da tabela lista as diferentes partes cobertas pelo guia de estilo: conceitos, vocabulário, verbosidade, gramática e pontuação.

Juntos, eles formam um guia de estilo . O cabeçalho apresenta os valores e o lado esquerdo da tabela mostra os diferentes componentes que você encontraria em qualquer material escrito: vocabulário, gramática e pontuação. A beleza deste guia de estilo é que engenheiros e redatores saberão claramente qual capitalização usar e qual pontuação usar para promover a identidade da marca Tapp.

Guia de Estilo de Redação Técnica

Nem todos os guias de estilo vêm em tabelas. A Microsoft tem um site inteiro que serve como um guia abrangente, cobrindo tudo, desde siglas até comunicação sem preconceitos e chatbots. É claro que a Microsoft não é a única empresa que possui um guia de estilo. O Google também tem um.

O problema com os guias de estilo

Os guias de estilo são um ótimo ponto de partida para empresas que levam a documentação a sério. Eles resolvem muito da confusão que os desenvolvedores podem ter sobre como exatamente escrever sobre um recurso importante que eles estão lançando.

O problema com os guias de estilo é que eles adicionam atrito ao processo de escrita. Muitos escritores, inclusive eu, não se preocupam em parar de escrever e olhar para o guia de estilo toda vez que têm uma pergunta. Às vezes, um guia de estilo é complicado e muito difícil de consultar – por exemplo, o Guia de Estilo da Microsoft tem mais de mil páginas!

Linters e CI/CD para Documentação

Se você é um programador, provavelmente está familiarizado com linters. Os linters são uma maneira ideal de impor padrões de codificação em sua equipe. O mesmo acontece com a documentação. Ao criar um linter, você está definindo uma referência de qualidade para sua documentação. Neste tutorial, vamos usar o linter Vale.

Usar algum tipo de automação de documentação junto com um linter é comum. Quando dizemos automação neste contexto, estamos nos referindo ao fluxo de trabalho de integração contínua e implantação contínua (CI/CD). CI automatiza a construção e teste de documentação . O CD automatiza a liberação do código.

Você pode usar muitos tipos diferentes de aplicativos para implementar um fluxo de trabalho de CI/CD. Neste tutorial, usaremos o GitHub Actions para executar nosso linter de documentação. As ações do GitHub executam CI diretamente em um repositório do GitHub, portanto, não há necessidade de usar um aplicativo de terceiros, como CircleCI ou Travis.

Por fim, as ações do GitHub são orientadas a eventos , o que significa que são acionadas quando algo acontece, como quando alguém escreve um pull request ou um problema. Em nosso exemplo, uma ação do GitHub ocorrerá quando alguém enviar as alterações para sua ramificação principal.

Ações do GitHub

Primeiro, crie um repositório GitHub. Então, localmente, crie uma pasta e cd nela.

 mkdir automated-docs cd automated-docs

Quando estiver na pasta, inicialize o diretório do Git.

 git init

Depois de inicializar o repositório, prossiga para criar um diretório de fluxo de trabalho para sua pasta.

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

Os fluxos de trabalho são onde armazenaremos todas as nossas ações do GitHub. Depois de criar uma pasta de workflows de trabalho, crie um novo fluxo de trabalho. Vamos nomear esse fluxo de trabalho vale.yml .

 touch vale.yml

Vale.yml é um arquivo YAML. Neste arquivo de fluxo de trabalho, incluiremos ações e trabalhos.

Agora, abra vale.yml em seu editor de texto favorito.

 nano vale.yml

Copie e cole o seguinte em vale.yml e vamos analisar o contexto e a sintaxe.

 # 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
  Este é o nome, ou o que estamos chamando de nosso fluxo de trabalho. É uma corda.
• on
  Isso controla o fluxo de trabalho e os gatilhos.
• jobs
  É aqui que configuramos e controlamos nossas ações. Selecionamos o ambiente onde nossas ações serão executadas — geralmente é uma boa aposta ir com o Ubuntu. E é aqui que vamos somar nossas ações.

O GitHub tem um guia sobre todas as outras sintaxes e variáveis ​​de fluxo de trabalho, caso você esteja curioso.

Nesta seção, temos:

• aprendi quais são as ações do GitHub,
• criamos nosso primeiro fluxo de trabalho do GitHub,
• identificou as partes mais importantes de um arquivo YAML de fluxo de trabalho do GitHub.

Em seguida, vamos personalizar nosso fluxo de trabalho do GitHub para usar o Vale.

Configurar Vale no arquivo de ações do GitHub

Depois de copiar o arquivo base do workflow, é hora de customizá-lo, para que possamos começar a usar as ações da Vale. A primeira coisa a fazer é alterar o nome do arquivo YAML para Docs-Linting .

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

Em seguida, queremos executar o teste do Vale assim que alguém enviar suas alterações para o branch principal no GitHub. Não queremos que o teste seja executado quando alguém cria uma solicitação pull, portanto, excluiremos essa parte do arquivo YAML.

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

A seção de jobs é a parte principal do arquivo de fluxo de trabalho e é responsável por executar as ações do GitHub.

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

Essas ações serão executadas na versão mais recente do Ubuntu. A ação Checkout verifica o repositório para que o fluxo de trabalho do GitHub o acesse.

Agora é hora de adicionar uma ação Vale ao nosso fluxo de trabalho do 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}}

Chamamos nossa ação de Vale . A variável uses mostra qual versão do Vale vamos implementar — o ideal é usar a versão mais recente. Na variável with , definimos debug como true .

A seção de styles nos dá a opção de adicionar um guia de estilo à Vale. Neste exemplo, usaremos o write-good e o guia de estilo oficial da Microsoft. Lembre-se de que também podemos usar outros guias de estilo.

A parte final desta ação do GitHub é env . Para executar essa ação do GitHub, precisamos incluir um token secreto.

É assim que o resultado deve ficar:

 # 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}}

Depois de terminar de fazer as alterações, salve o arquivo, confirme no Git e envie suas alterações para o GitHub.

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

Para recapitular, nesta seção, temos:

• acionou a ação para ocorrer quando enviamos um novo código para a ramificação main ;
• adicionou uma ação Vale, definindo debug para true e identificando guias de estilo;
• adicionou um token do GitHub;
• alterações confirmadas e enviadas para o GitHub.

Na próxima seção, vamos criar um arquivo de configuração Vale.

Configurando o arquivo de configuração do Vale

Vá para a raiz do diretório do seu projeto e touch .vale.ini . Abra .vale.ini em um editor de texto. Copie e cole o seguinte em .vale.ini :

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

• StylesPath = .github/styles
  O StylesPath fornece o caminho dos estilos Vale.
• MinAlertLevel = warning
  O nível mínimo de alerta mostra a escala de gravidade dos alertas. As opções são suggestion , warning e error .
• [formats]
Markdown = markdown define o formato como Markdown.
• [*.md]
  A configuração BasedOnStyles = write-good, Microsoft executará write-good e o guia de estilo da Microsoft em todos os arquivos Markdown que terminam com .md .

Esta configuração é o mínimo. Caso tenha interesse em saber mais sobre como configurar a Vale, acesse a documentação.

Quando terminar de fazer as alterações, salve o arquivo, confirme e envie para o GitHub.

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

Nesta parte, aprendemos os detalhes internos de um arquivo de configuração Vale. Agora é hora de criar a documentação de amostra.

Criando documentação e acionando as ações Vale GitHub

Agora é hora de ver o Vale e o GitHub Actions em ação! Vamos criar um arquivo Markdown e preenchê-lo com texto. E vamos receber nosso texto do DeLorean Ipsum.

Vá para a raiz do seu projeto e touch getting-started.md . Depois de criar o arquivo de getting-started , vá para o DeLorean Ipsum e crie um texto fictício para sua documentação. Em seguida, retorne ao seu editor de texto e cole o texto em 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?

Salve o arquivo, confirme-o e envie-o para o GitHub.

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

Depois de enviar as alterações, vá para o GitHub, onde seu repositório está localizado. Vá para a guia Actions .

Você verá todos os seus fluxos de trabalho no lado esquerdo. Temos apenas um, chamado Docs-Linting , o mesmo nome que colocamos no arquivo vale.yml .

Quando enviarmos a documentação para o GitHub, acionaremos a ação.

Se a ação foi executada sem problemas, receberemos uma marca de seleção verde.

Clique em “Documentos adicionados” para obter um relatório completo.

Você verá que recebemos 11 avisos. Vamos lidar com o aviso da “palavra doninha”. Volte para o editor de texto, abra getting-started.md e exclua a palavra “exatamente”.

 # 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?

Salve as alterações, confirme no Git e envie a nova versão do arquivo para o GitHub. Ele deve acionar a ação do GitHub .

Se clicarmos em “Deleted the weasel word”, veremos que temos apenas 10 avisos agora, e o aviso de “weasel word” desapareceu. Viva!

Nós terminamos e cobrimos muito terreno. Nesta seção, temos:

• adicionamos documentação ao nosso repositório Vale GitHub Actions,
• desencadeou a ação Vale GitHub,
• corrigiu um erro produzido pela Vale e empurrou a alteração de volta para o GitHub.

Conclusão

Em um mundo cada vez mais remoto, é importante priorizar uma boa documentação e um bom fluxo de trabalho de documentação. Você primeiro precisa definir o que é “bom” criando um guia de estilo. Depois de descobrir as regras da sua documentação, é hora de automatizar.

A documentação deve ser tratada como sua base de código: um corpo de trabalho vivo que está constantemente sendo iterado e se tornando um pouco melhor do que a última vez que você o atualizou.