samykabu/manual-do-usuario

Manual do Usuário

Mantenha uma fonte única em Markdown com evidências sob User-Manual/. Publique três edições: Usuário Final, Administrador/Operador e Referência Técnica. Markdown é o produto; a renderização é uma etapa separada e substituível.

Escolha o menor fluxo de trabalho

• Novo manual: entreviste o usuário, inspecione o repositório, proponha um mapa de módulos, obtenha aprovação, então execute scripts/init_manual.py com um arquivo JSON de módulos aprovado.
• Manual existente: leia User-Manual/manual.yml, inspecione o escopo solicitado e o diff Git relevante, então atualize apenas as páginas e ativos afetados.
• Auditoria de cobertura: execute scripts/audit_manual.py e explique cada erro e aviso.
• Construção: execute scripts/build_manual.py apenas após a auditoria passar. Ele monta cada edição, depois a renderiza com renderer.kind em manual.yml: markdown (padrão), command ou mkdocs.
• Atualização: scripts/manual_state.py record --feature <dir> após uma atualização; status retorna 1 quando as entradas ou saídas do manual mudaram desde o registro.

init_manual.py copia os scripts de construção, auditoria e estado (e as folhas de estilo fornecidas, em tools/theme/) para User-Manual/tools/ para CI. Após atualizar este skill, atualize essas cópias a partir de seu diretório scripts/. --no-tools pula as cópias quando o CI executa os scripts de outro local. Os fluxos de trabalho de CI seguem o mapeamento ci: em --ci-policy <file>, senão em .specify/workflow.yml quando existir.

Este skill não requer .specify/, uma especificação de recurso ou qualquer comando do Spec Kit. Escopo do trabalho a partir da solicitação do usuário, evidências do repositório e alterações de controle de versão.

Roteie apenas o necessário

Tarefa	Leia
Descoberta e entrevista	descoberta.md
Estrutura de página e sintaxe Markdown	modelo-de-conteudo.md
Público e idioma	audiencia-idioma.md
Alterações incrementais	atualizacao-incremental.md
Entidades, colunas, enumerações, diagramas ER	referencia-de-dados.md
Renderizadores, modelos, marca, HTML, PDF, RTL	publicacao.md
Documentação de API	docs-api.md
Notas de versão e guias de migração	docs-de-lancamento.md
Capturas de tela da interface	capturas-de-tela.md
Pré-visualizações e publicação de lançamentos	previa-publicacao.md

Regras inegociáveis

1. Exigir inglês. Árabe é opcional por projeto, mas páginas, renderizadores, diagramas e PDFs devem suportar RTL desde a inicialização.
2. Use inglês ou árabe natural e simples. Escreva para o público declarado; nunca reutilize uma explicação técnica inalterada para um usuário final.
3. Baseie afirmações em implementação, contratos, testes, comportamento observado, esquemas ou fontes de infraestrutura aprovadas. Marque itens desconhecidos e nunca invente comportamento.
4. Nunca inclua segredos, credenciais, tokens, chaves privadas, strings de conexão, registros de produção ou dados pessoais não editados. Use exemplos sintéticos determinísticos.
5. Armazene o mapa de módulos aprovado e extensível em User-Manual/manual.yml. Adicione descobertas posteriores como proposto até aprovação.
6. Mantenha o Markdown canônico e escreva a sintaxe nativa do GitHub, para que cada página seja lida corretamente no GitHub; a construção o traduz para outros renderizadores. Gere outros formatos apenas por meio da construção.
7. Gere apenas diagramas úteis, com o skill ilustrar quando instalado. Mantenha visões gerais do sistema separadas dos detalhes legíveis de nível de módulo: uma visão geral ER do sistema mais diagramas ER de módulos menores. Documente cada entidade, coluna, tipo de dado, relacionamento, restrição e enumeração com evidências.
8. Preserve conteúdo editado manualmente fora de marcadores próprios e faça com que as reexecuções convinjam.
9. Vincule uma página apenas a páginas que seu público recebe. A construção rejeita links entre públicos e ativos ausentes, e prepara apenas os ativos que as páginas de uma edição alcançam, para que um público nunca envie capturas de tela ou amostras de outro.

Exemplo real

Para "Criar um manual para nossa plataforma de reservas," identifique módulos de reserva, cliente, pagamento e operações a partir de rotas, navegação, APIs, testes e arquivos de esquema. Peça ao usuário para aprovar esse mapa de módulos. Em seguida, crie tutoriais conscientes do público, capturas de tela seguras, referências de API e dados, conteúdo em inglês e conteúdo opcional em árabe sob User-Manual/, e renderize-o da maneira que o projeto escolher: Markdown no GitHub, o modelo Word da equipe via Pandoc, ou um site MkDocs com PDFs.