Como escrever documentação que o time abre, lê e segue

A Agência Pomar (fictícia) tem um procedimento de publicação de post com quatro páginas. O estagiário abriu na segunda, desistiu na segunda página e perguntou ao colega. O procedimento estava correto, mas foi escrito para quem tem tempo, e não para quem está no meio de uma tarefa. Documentação que se lê segue poucas regras, todas aplicáveis hoje.

Por que as pessoas não leem a documentação da empresa?

Porque a página não responde à pergunta que a pessoa trouxe. Quem abre um procedimento está no meio de uma tarefa, com pressa, e quer o próximo passo. Título vago, introdução longa e passos escondidos em parágrafos fazem do colega ao lado o caminho mais curto.

Como fica a mesma página antes e depois da reescrita?

Veja o procedimento de publicação de post da Agência Pomar (fictícia) reescrito. O conteúdo é o mesmo; mudam o título, a abertura, a forma dos passos e a presença de dono e data.

Nada foi cortado do conteúdo. A reescrita só colocou a resposta no lugar em que a pessoa a procura.

Quais são as regras de estilo da documentação que se lê?

Sete regras bastam. Valem para procedimento, política, guia de cliente ou wiki, e cada uma pode ser conferida em segundos no fim da escrita.

1. Título que responde. “Como publicar um post aprovado”, e não “Procedimento de publicação”. A pessoa reconhece o que procura pelo título.
2. Abertura de duas linhas. Quando usar e quanto tempo leva. Quem não está no caso certo sai logo.
3. Passo numerado, um verbo por passo. “Abra a agenda de publicações”, e não “o acesso deve ser feito pela agenda”.
4. Um exemplo preenchido. Um caso real ensina mais que três parágrafos de regra.
5. Uma ideia por parágrafo. Se o parágrafo tem duas, são dois parágrafos.
6. Frases curtas, na voz ativa. “O atendimento confirma a data” no lugar de “a data deve ser confirmada”.
7. Dono e data no topo. Quem responde pela página e quando foi revisada. Página sem dono envelhece sem aviso.

Qual é o template de página que funciona para qualquer procedimento?

O template tem poucos campos e cabe numa tela. O que ele impõe é a ordem: primeiro o que a pessoa precisa decidir (devo ler isto?), depois o que fazer, por último o que fazer quando algo dá errado.

[TÍTULO QUE RESPONDE: Como + verbo + resultado]

Dono: [nome]
Revisado em: [data]
Próxima revisão: [data]

Quando usar: [a situação, em uma linha]
Tempo: [minutos]
Você precisa de: [acessos e materiais]

PASSOS
1. [Verbo + o que fazer]
2. [Verbo + o que fazer]
3. [Verbo + o que fazer]
4. Conferir: [como saber que deu certo]

EXEMPLO
[Um caso real, preenchido; use nome fictício se a página for pública]

SE DER ERRADO
- [Problema comum] → [o que fazer]
- [Outro problema] → [quem chamar]

VEJA TAMBÉM
- [Link para a página anterior ou seguinte do processo]

Como revisar a página antes de publicar?

O teste mais confiável é pedir a alguém de fora da área que siga os passos sem ajuda, enquanto você observa em silêncio. Onde a pessoa hesita, o texto falha. Cinco minutos de teste valem mais que uma hora de releitura.

CHECKLIST DE ESTILO
( ) O título responde a uma pergunta do tipo “como faço X?”
( ) A abertura diz quando usar e quanto tempo leva
( ) Todos os passos começam com verbo
( ) Há um exemplo preenchido
( ) Cada parágrafo tem uma ideia só
( ) Nenhuma frase passa de 25 palavras
( ) Dono e data de revisão estão no topo
( ) Alguém de fora da área seguiu os passos sem ajuda
( ) A seção “Se der errado” tem pelo menos um caso

Para documentar um processo inteiro, e não uma página, siga o passo a passo de como documentar processos e use o modelo de manual de processos como estrutura. Para o nome dos arquivos, veja o padrão de nomenclatura de arquivos.

Como escrever e manter a documentação no Mentrun?

No Mentrun, a documentação mora em Documentos. O modelo de procedimento já traz a ordem do template acima, e a situação e a data de revisão evitam que a página envelheça em silêncio.

1. 1

   Novo documento, modelo Procedimento (SOP)

   O modelo traz Objetivo, Quando usar, Responsável, Tempo estimado e Situação, mais Antes de começar, Passo a passo e Checklist final. Toque em Prévia para ver antes de usar.

2. 2

   Escreva e ligue as páginas

   Digite [[ para ligar um documento a outro. A página ligada passa a mostrar “Citado por”.

3. 3

   Marque dono e revisão

   Em Situação e revisão, escolha Rascunho ou Aprovado, a data da próxima revisão e o responsável. O responsável recebe aviso quando a revisão vence.

4. 4

   Peça o primeiro rascunho ao Assistente

   No Assistente, em Minha empresa, peça “cria um SOP de publicação de post com estes passos: …”. Ele mostra a prévia num cartão e só cria quando você toca em Aplicar, com Desfazer no mesmo cartão. Releia, corte e confira cada passo antes de aprovar.

5. 5

   Use o procedimento na tarefa

   Em Usar procedimento, os passos viram o checklist da tarefa, e quem executa não precisa abrir outra página.

Quando o procedimento nasce de uma reunião em que alguém explicou o trabalho falando, o guia de IA para documentar processos mostra o caminho da gravação ao texto, com a revisão humana no final.

Como a IA dentro do documento ajuda a cortar e reescrever?

Selecione o trecho que ficou comprido e toque em IA (ou Ctrl+J): a IA deixa mais curto, corrige o português, muda o tom para simples ou transforma o parágrafo em lista ou checklist. Você vê a prévia e escolhe Substituir ou Inserir abaixo antes de qualquer mudança.

• Passos comprimidos: peça Checklist para o parágrafo que mistura ações e confira se cada item ficou com um verbo.
• Escrever do zero: num bloco vazio, digite /ia para escrever sobre um assunto, continuar o texto ou criar a partir de uma reunião, de um projeto ou de um modelo.
• Outro idioma: traduza o trecho para inglês ou espanhol sem perder os links para outros documentos.
• Sem risco: Ctrl+Z volta o texto, e cada salvamento guarda a versão.

A IA corta e reescreve; o teste com alguém de fora da área continua sendo seu. O recurso está em editor de documentos com IA, e o texto sobre escrita assistida, em IA para escrever documentos.

Quais erros deixam a documentação longa e ignorada?

Quase todos nascem do mesmo hábito: escrever para provar que o processo existe, e não para ajudar quem vai executá-lo. A correção é sempre a mesma pergunta: o que esta pessoa precisa saber agora?

• Introdução institucional. “A empresa preza pela excelência” não ajuda a publicar um post. Troque por quando usar e quanto tempo leva.
• Passos que misturam ações. Um passo com três verbos esconde o erro. Separe em três.
• Sem exemplo. A pessoa copia o exemplo antes de ler a regra. Sem ele, cada um interpreta de um jeito.
• Página sem dono. Ninguém corrige o que não é de ninguém. Coloque um nome e uma data de revisão; o hábito de manter a página viva está na cultura de documentação.
• Um documento para tudo. Quando passa de duas telas, divida por tarefa. O modelo de procedimento operacional padrão mostra o tamanho certo.