Style Guide
Escreva documentação do jeito da Azion: voz, estrutura de frases, terminologia, formatação, tipos de conteúdo e convenções de arquivos.
Este guia descreve como a Azion escreve sua documentação. Use este guia quando você escrever uma página nova, traduzir uma página ou revisar o trabalho de outra pessoa. As regras existem para que todas as páginas tenham a mesma leitura, sejam bem traduzidas e continuem úteis quando uma máquina recupera uma seção sozinha.
O que este guia cobre
- Voz da documentação: o registro que todas as páginas usam.
- Estrutura de frases: as regras de frase, adaptadas do ASD-STE100.
- Procedimentos: a gramática de passo que todo procedimento numerado segue.
- Escolha de palavras: o vocabulário a evitar e os padrões de enchimento a cortar.
- Terminologia da documentação: nomes de produtos, os quatro termos da plataforma e regras de tradução.
- Títulos, formatação de texto, código, pontuação e números e unidades: como o conteúdo é formatado.
- Estrutura de conteúdo: os tipos de página e como escolher um, incluindo quickstarts e casos de uso.
- Arquitetura de informação: os treze slots que uma seção de produto pode preencher, na ordem em que o leitor os encontra.
- Convenções de arquivos: frontmatter e páginas bilíngues.
- Componentes: o conjunto de componentes MDX ativos e as regras de cada um.
- Como escrevemos a documentação: como a documentação é produzida, em dois idiomas, para pessoas e agentes.
O guia segue as próprias regras
Todas as páginas desta seção passam pelas regras que descrevem: os limites de frase, as regras de títulos e as metas de tamanho. Quando uma regra não funciona aqui, a regra muda antes de qualquer pessoa precisar segui-la.