Docs as code
Entenda como a documentação é publicada: um repositório público, um fluxo de revisão que começa na issue e verificações automáticas em toda mudança.
A documentação é uma base de código. Cada página é um arquivo em um repositório público, e cada mudança é um pull request. Cada pull request passa pelas mesmas verificações automáticas antes de ser publicado.
Um repositório, uma revisão
O código-fonte vive em aziontech/docs no GitHub, aberto a contribuições externas. Para mudanças significativas, a issue vem antes do pull request, para que um mantenedor avalie a abordagem antes do trabalho começar. Correções menores podem ir direto para um pull request.
Dois times fazem as revisões: Developer Education guarda o conteúdo, e UX Engineering guarda o código de estrutura. Os templates de issue do repositório encaminham cada pedido: reportar um erro, pedir uma adição, atualizar conteúdo ou fazer uma pergunta.
As verificações que toda mudança passa
O build verifica uma mudança de quatro formas:
| Verificação | O que ela captura |
|---|---|
| Build do site | Uma página que não compila: um componente quebrado, MDX malformado, um import inválido |
| Validador de frontmatter | Um namespace ou permalink ausente, malformado ou duplicado |
| Verificação de sidebar | Uma entrada de menu apontando para um permalink que não existe, e uma página inalcançável por qualquer menu |
| Verificador de links | Um link interno cuja página de destino não existe |
Uma mudança que falha em qualquer uma delas não é mesclada.
Redirects
Um permalink que muda ou desaparece publica seu redirect na mesma mudança. Os pares de redirect são declarados no repositório e aplicados pela camada da plataforma que serve o site.
Metadados
Toda página carrega os mesmos cinco campos de frontmatter, e dois deles são contratos. O permalink é único por idioma, e o namespace conecta a página à sua tradução. O contrato completo está em Convenções de arquivo.