Skip to content

Contribuição

Como contribuir e evoluir a documentação da HÉLICO com consistência editorial e terminológica.

Contribuição e Evolução da Documentação

Contexto

A documentação da HÉLICO é um ativo de produto e operação. Este guia define como evoluir conteúdo com consistência editorial e terminológica.

Problema

Edições sem gestão de alterações geram divergência entre áreas, perda de rastreabilidade e ambiguidades conceituais.

Solução

Padronizar contribuição em três eixos:

  1. padrões de termos;
  2. fluxos editoriais;
  3. decisões e dúvidas.

Padrões de termos

Tudo isto vive neste repositório, o middag-io/docs-helico. O catálogo de termos saiu do moodle-local_helico na issue #159; o plugin passou a consumi-lo por commit fixado.

Regra Fonte canônica
Cadastro de termos .vigim/ddd/terms/terms*.yaml, por domínio
Schema dos termos middag-io/dev-tools, em resources/vigim/ddd/terms/terms.schema.yaml
Tooltips de abreviação (gerado) .vigim/ddd/terms/generated/terms-abbreviations.md
Glossário (gerado) dev/glossary/

Regra obrigatória

Tudo sob .vigim/ddd/terms/generated/ e todo o dev/glossary/ é gerado automaticamente. Edite o catálogo e rode npm run build:terms; nunca edite a saída. O CI roda npm run check:terms e falha se qualquer um dos dez artefatos sair de sincronia com o catálogo.

O moodle-local_helico lê estes mesmos arquivos para gerar código e validar o vocabulário, mas não guarda cópia: ele baixa o diretório pelo commit fixado em .vigim/ddd/terms.lock, conferindo o sha256 de cada arquivo (cli/sync-terms.sh de lá).

Consequência prática: mudança de termo entra por PR aqui. Para o plugin enxergá-la, o terms.lock de lá precisa apontar para o commit novo — enquanto não apontar, ele segue com a versão fixada, de propósito.

Pipeline CLI de termos

Comando Finalidade Efeito
npm run build:terms Validar e gerar os artefatos Reescreve generated/, reports/ e o glossário
npm run check:terms Conferir sem escrever Falha se a saída divergir do catálogo

O schema continua no dev-tools — ele descreve o formato do catálogo para toda a MIDDAG, não só para a HÉLICO. O que mudou de lugar foi o catálogo, não a regra que o descreve.

O gerador era PHP, também no middag-io/dev-tools, e foi portado para Node junto com a migração — a fidelidade é verificada contra os artefatos originais, byte a byte, em scripts/tests/artifacts.test.mjs. A proveniência está no SOURCES.md.

Fluxos editoriais

Fluxo de atualização de páginas

  1. definir escopo e objetivo da alteração;
  2. revisar termos no glossário e na página afetada;
  3. aplicar atualização com estrutura editorial padrão;
  4. validar links e consistência semântica;
  5. registrar dúvida pendente quando necessário.

Padrão editorial por página

Toda página de conteúdo crítico deve cobrir, quando aplicável:

  • Contexto
  • Problema
  • Solução
  • Conceitos/Definições
  • Regras e Dependências
  • Prós e Contras
  • Notas de Contexto
  • FAQ local (apenas se área crítica)

Decisões e dúvidas

  1. Marcar a dúvida no ponto do conteúdo com !!! question.
  2. Registrar formalmente em .vigim/content/metodologia/duvidas-metodologia.md no formato padronizado.
  3. Após decisão, atualizar FAQ central ou FAQ local correspondente.

Referências e qualidade

  • Priorizar referências internas (metodologia e glossário).
  • Usar referências externas curadas para fundamentar princípios pedagógicos quando necessário.
  • Garantir coerência terminológica entre pedagógico, produto, técnico e operação.
Navigation

Type to search…

↑↓ navigate↵ selectEsc close