logo hsb.horse

Registro de Decisão de Arquitetura

Política de introdução da coleção Snippets para notas práticas curtas

Separar em snippets as notas práticas curtas demais para o blog, com páginas de lista e detalhe em /snippets e /{lang}/snippets.

Aceito #content #snippets #blog #information-architecture #seo

Política de introdução da coleção Snippets para notas práticas curtas

Decision

  • Notas práticas curtas (trechos de comando, procedimentos mínimos, exemplos curtos de configuração) ficam em snippets.
  • O modelo de conteúdo passa a ter três tipos: posts cronológicos em blog, conteúdo de referência em glossary e trechos práticos em snippets.
  • Adicionar a coleção snippets e implementar rotas de lista/detalhe em /snippets e /{lang}/snippets.
  • Manter _template.ja.md e excluir da publicação arquivos com prefixo _.

Context

O modelo atual não tinha um local claro para notas práticas curtas:

  • Curtas demais para um post de blog
  • Não são páginas de definição para glossário

Misturar esse tipo de conteúdo no blog torna ambíguos o objetivo da listagem e a intenção de busca.
glossary é orientado a definições e não se ajusta bem a snippets centrados em comandos.

Options

  • Option A: Manter notas práticas curtas no blog.
  • Option B: Colocar em glossary.
  • Option C: Criar a coleção dedicada snippets (escolhida).

Rationale

  • Os pontos de entrada ficam mais claros: artigos, conhecimento e snippets práticos.
  • Isolar notas curtas ajuda a manter o padrão de qualidade dos artigos do blog.
  • Separar URLs deixa mais clara a intenção da página para mecanismos de busca.

Consequences

  • Adicionar o schema da coleção snippets em src/content.config.ts.
  • Adicionar src/features/snippets/*, src/pages/snippets/* e src/pages/[lang]/snippets*.
  • Adicionar textos de snippets na navegação de cabeçalho e nos dicionários de i18n.
  • Migrar o primeiro conteúdo (nota de conversão em lote com avifenc) para content/snippets/.