# Escrevendo documentação

> Como uma página de documentação é estruturada, quais verificações ela precisa passar e quais páginas são geradas.

Source: https://alexgalhardo.github.io/vukem-video/pt-br/docs/contributing/writing-docs/

## O que você vai aprender

- a estrutura que toda página segue;
- como adicionar uma página e onde ela aparece;
- as verificações que rodam no site, e as páginas que você não deve editar.

## A ideia

Um recurso não está terminado até a sua página existir. As páginas são arquivos MDX em `site/content/docs/en/<dir>/<slug>.mdx`; o arquivo em inglês é a fonte de verdade, e o arquivo em português do Brasil com o mesmo caminho é a sua tradução. A referência de comandos, as referências da CLI e da API HTTP, os códigos de erro e as variáveis de configuração são geradas a partir do código, então não podem divergir.

## Início rápido

1. Crie `site/content/docs/en/<dir>/<slug>.mdx` com um `title` e uma `description` no front matter.
2. Escreva as seções nesta ordem: `You will learn` (páginas de guia e de primeiros passos), `The idea` (de duas a cinco frases, nas palavras do glossário), `Quick start` (passos numerados com o comando exato e o resultado), `Common mistakes` (cada um com o seu código de erro quando houver) e `Next steps`.
3. Mostre uma ação para cada superfície que a tem: a interface, o comando da CLI, a ferramenta MCP e os argumentos, e a chamada HTTP. Use os nomes das definições compartilhadas.
4. Adicione o slug a `site/content/navigation.ts`, na categoria da sua pasta.
5. Execute as verificações a partir de `site/`:

```bash
npm run check:mdx
npm run build
npm run check:built
npm run lint
npm run check:command-mentions
npm run last-updated
```

## As regras de uma página

- Os links são relativos à raiz, como `/docs/guide/exporting`. O `check:mdx` falha em um link para uma página que não existe, e em um link para um título que não existe.
- Nenhum `{` ou `<` solto em prosa, nenhum HTML fora dos componentes MDX, linhas de código de no máximo 100 caracteres, e uma linguagem em todo bloco de código.
- Código, nomes de comandos, opções, códigos de erro e identificadores ficam em inglês nos dois idiomas.
- Uma página de guia nomeia o comando que faz o que ela ensina, e todo comando que ela nomeia precisa existir (`check:command-mentions`).
- Nenhum texto de marketing e nenhuma afirmação de desempenho sem uma medição e a sua fonte.
- Um recurso que não está na versão publicada leva um aviso, que o pull request que o entrega remove.

## Erros comuns

- Editar uma página em `site/content/generated/`: ela é sobrescrita por `npm run reference`, e o `reference:check` falha em uma diferença. Mude o registro Go, o esquema ou `site/scripts/generate-reference.ts`, depois regenere.
- Esquecer o `npm run last-updated`: a verificação "Last updated" falha quando uma página é mais nova que a sua data registrada.
- Linkar a página pt-BR pelo seu próprio caminho. Escreva o mesmo link `/docs/...` nos dois idiomas; o site o reescreve para o português.
- Descrever um recurso de memória. Confira a página contra o código e a especificação, e diga o que você não conseguiu verificar.

## Próximos passos

- [Traduzindo a documentação](/docs/contributing/translating)
- [Commits e pull requests](/docs/contributing/commits-and-prs)
