Ir para o conteúdo

Contribuindo

Escrevendo documentação

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

Última atualização:

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/:
Terminal
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#