Escrever documentação B1

Nível: B1

Objetivo

Escrever documentação técnica de porte médio (READMEs detalhados, design docs, runbooks) com uma estrutura clara — Objective, Context, Prerequisites, Steps, Troubleshooting, Examples — usando voz ativa, linguagem concisa e terminologia consistente para engenheiros e times de produto.

Explicação

Documentação B1 não é só uma lista de comandos: é um texto que outra pessoa consegue seguir sem te perguntar nada. A estrutura recomendada tem seis blocos, nesta ordem:

1. Objective — o que o leitor vai conseguir fazer depois de ler o documento. Use uma ou duas frases começando com um verbo de ação: *This guide shows you how to deploy the staging environment.*
2. Context — por que o documento existe e qual problema ele resolve. Inclua o nome do sistema, o público-alvo e o cenário: *The DataSync service runs nightly and is owned by the Data Platform team.*
3. Prerequisites — o que o leitor precisa ter antes de seguir os passos: contas, permissões, versões de software, acesso à VPN, chaves de API. Use uma lista com marcadores.
4. Steps — os passos numerados, um verbo imperativo por linha, em voz ativa. *Run `make deploy`*, não *The command should be run*.
5. Troubleshooting — erros comuns e como reagir: *If you see `403 Forbidden`, regenerate the token with `auth-cli refresh`.*
6. Examples — entradas e saídas esperadas, blocos de código, diagramas, payloads de API.

Clareza vem de três hábitos: frases curtas (uma ideia por frase), voz ativa sempre que possível, e o mesmo termo para o mesmo conceito. Se você chama o serviço de `DataSync` no começo, não troque para `the data sync tool` no meio do texto. Consistência de terminologia é o que diferencia um texto profissional de um rascunho.

Voz ativa vs. voz passiva: a voz ativa diz *who does what*; a passiva esconde o ator. Em documentação, a ativa é quase sempre melhor porque mostra quem executa a ação:

• Ativa: *The scheduler runs the job every night.*
• Passiva: *The job is run by the scheduler every night.*
• Fraca: *The job is run every night.*

A passiva só é aceitável quando o ator é irrelevante ou desconhecido: *The configuration is loaded from `config.yaml`.* Aqui importa o que acontece, não quem faz.

Verbos imperativos nos passos mantêm o texto curto: *Click*, *Run*, *Open*, *Verify*, *Confirm*. Evite *you should click* ou *it is recommended to run* — dizem o mesmo com mais palavras.

Consistência também vale para formato: decida se vai usar `npm install` ou `npm i` e mantenha; decida se headings vão em `Sentence case` ou `Title Case` e mantenha; decida se listas de pré-requisitos usam `-` ou `*` e mantenha.

Quando escrever em voz passiva: introduza a regra com parcimônia. Em uma única runbook, prefira 90% de ativa; reserve a passiva para carregamentos, validações e importações automáticas, em que o ator é o sistema e não importa.

Exemplos

Erros comuns

• Esconder o ator na voz passiva: `The job is run nightly` perde informação; prefira `The scheduler runs the job nightly`.
• Começar passos com `you should` ou `it is recommended to`: troque por imperativo simples — `Run`, `Open`, `Verify`.
• Misturar nomes do mesmo conceito: se o serviço é `DataSync`, mantenha `DataSync`; não troque por `the data sync tool` no meio do texto.
• Pular a seção de pré-requisitos: o leitor descobre, no passo 4, que faltava uma API key. Liste tudo no Prerequisites.
• Colocar Troubleshooting antes de Steps: o leitor ainda não sabe o que está fazendo e não consegue reagir a erros.
• Usar frases longas e subordinadas em passos: *After you have finished configuring the environment, you should run the build command.* vire `Run the build command.`
• Inconsistência de formato: alternar `npm install` e `npm i`, ou usar `Title Case` em um heading e `Sentence case` no outro, confunde o leitor.

Prática guiada

Reescreva este parágrafo como uma seção Objective + Prerequisites clara:

> The way the system works is that you need to first have the API key generated and then the user should clone the repository, after that it is recommended to run the build and then the deployment will be performed by the script.

Versão reescrita:

• Objective: deploy the application to staging.
• Prerequisites: an API key in `.env` as `API_KEY`, Node.js 18+, and access to the `deploy` script.
• Steps:

1. Clone the repository.
2. Run `make build`.
3. Run `make deploy STAGE=staging`.

Observe o que mudou: voz ativa em todo lugar, imperativos curtos, lista numerada, pré-requisitos listados antes dos passos. A informação é a mesma; a leitura é muito mais rápida.

Resumo

Documentação B1 segue a estrutura Objective, Context, Prerequisites, Steps, Troubleshooting, Examples. Use voz ativa, verbos imperativos nos passos, frases curtas e terminologia consistente do começo ao fim.

História: Escrever documentação B1

Nível: B1

História em inglês

The new runbook nobody could follow

On Wednesday morning, Mark joined the Data Platform team as a senior engineer. His first task was to review the runbook for the nightly DataSync service. The document was twelve pages long, but it didn't start with an objective. Most steps were written in the passive voice, so it was hard to tell who had to do what. There was no Prerequisites section, and the Troubleshooting section was buried at the end of the file.

Mark rewrites the document

Mark opened a pull request and replaced the entire document with a new version. He started with a single line: "This runbook shows you how to operate the DataSync service during a nightly run." The Context section explained that the service was owned by the Data Platform team and ran every night at 02:00 UTC. He added a Prerequisites list with four items: VPN access, a valid API key, the on-call pager, and a copy of the playbook. The Steps section used the imperative voice: "Verify the job queue." "Run the rollback script." "Confirm the dashboard status." The Troubleshooting section came right after the Steps, with the most common error messages and the exact command to fix each one.

Sofia reviews the changes

On Thursday, Sofia, the team's technical writer, opened the pull request and read the new version. She noticed that Mark had renamed the service halfway through the document, calling it "the data sync tool" instead of "DataSync". She left a comment: "Please keep the terminology consistent. We agreed on `DataSync` in our style guide." Mark fixed every occurrence in a few minutes and pushed the change again. Sofia approved the pull request and the new runbook went live the same afternoon. During the next on-call shift, the new engineer on rotation followed the runbook end to end and did not need to ping anyone for help.

Tradução linha por linha

Notas de vocabulário

• runbook = manual operacional usado em plantão; descreve como agir em cenários específicos
• DataSync = nome próprio do serviço; manter idêntico em todo o documento
• objective = primeira seção; declara o que o leitor vai conseguir fazer
• passive voice = voz passiva; esconde o ator e deixa a frase mais longa
• imperative voice = modo imperativo; forma curta e direta para passos (Run, Verify, Confirm)
• Prerequisites = seção que lista contas, versões e permissões antes dos passos
• Troubleshooting = seção que lista erros comuns e a ação corretiva para cada um
• terminology = terminologia; conjunto de nomes usados consistentemente no documento
• style guide = guia de estilo; documento de referência para terminologia e formato
• on-call = plantão; pessoa escalada para responder a incidentes fora do horário
• technical writer = redator técnico; profissional dedicado a revisar clareza e consistência
• pull request = solicitação de merge; espaço para revisão de código e de documentação

Perguntas de compreensão

1. What was Mark's first task on the Data Platform team?
2. Why was the original runbook hard to follow?
3. What did Mark write in the first line of the new runbook?
4. Which four items did Mark put in the Prerequisites section?
5. In which voice did Mark write the Steps section?
6. Where did Mark place the Troubleshooting section?
7. What consistency issue did Sofia find in Mark's draft?
8. How did Sofia justify her comment about the terminology?
9. What happened during the next on-call shift after the new runbook went live?

Prática com a história

1. Reescreva em voz ativa: The job is run by the scheduler every night at 02:00 UTC.
2. Reescreva o passo em imperativo direto: It is recommended that you run the rollback script before continuing.
3. Traduza: Pré-requisitos: Docker, Make e uma API key em `.env`.
4. Escreva uma frase de Troubleshooting para o erro `ECONNREFUSED` ao iniciar a API local.
5. Corrija a inconsistência: Mark começou chamando o serviço de DataSync e depois passou a chamá-lo de the data sync tool.