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:
- padrões de termos;
- fluxos editoriais;
- 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 odev/glossary/é gerado automaticamente. Edite o catálogo e rodenpm run build:terms; nunca edite a saída. O CI rodanpm run check:termse falha se qualquer um dos dez artefatos sair de sincronia com o catálogo.
Quem mais consome 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
- definir escopo e objetivo da alteração;
- revisar termos no glossário e na página afetada;
- aplicar atualização com estrutura editorial padrão;
- validar links e consistência semântica;
- 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
- Marcar a dúvida no ponto do conteúdo com
!!! question. - Registrar formalmente em
.vigim/content/metodologia/duvidas-metodologia.mdno formato padronizado. - 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.