Pular para o conteúdo principal
Versão: v0.2.2

Guia editorial

Voz​

  • Escreva em português do Brasil, com tom técnico e direto.
  • Use segunda pessoa ou sujeito oculto em instruções: “Configure”, “Execute”, “Verifique”.
  • Descreva comportamento verificável. Evite “robusto”, “completo”, “fácil” e outros adjetivos sem evidência.
  • Explique fundamentos de Go apenas quando forem necessários para usar o SDK.

Terminologia​

  • Use SDK para o Colibri e pacote para módulos Go.
  • Prefira “microsserviço”, “requisição”, “resposta”, “cabeçalho” e “corpo”.
  • Preserve nomes da API em inglês e entre crases: WebContext, Request, MiddlewareError.
  • Use “Go”, não “Golang”, exceto em termos de busca ou nomes próprios.

Estrutura​

Páginas de recurso devem seguir:

  1. propósito e momento de uso;
  2. configuração;
  3. inicialização;
  4. exemplo mínimo completo;
  5. retornos e erros;
  6. limites e cuidados;
  7. links relacionados.

Código​

  • Fixe a versão nos comandos go get.
  • Exemplos copiáveis incluem package, imports e tratamento de erro.
  • Use http.MethodGet e http.StatusOK em vez de strings ou números mágicos.
  • Qualifique símbolos pelo pacote: sqlDB.NewQuery, cacheDB.NewCache.
  • Use showLineNumbers somente em blocos longos.
  • Snippets parciais devem ser claramente apresentados como trechos.

Markdown​

  • Use o título do frontmatter como H1.
  • Comece seções em H2 e subseções em H3.
  • Use admonitions apenas para riscos, limitações e informações acionáveis.
  • Não finalize páginas com separadores horizontais.
  • Links internos devem ser relativos quando apontarem para outra página de documentação.