Orientação editorial para manuais técnicos

Estado: orientação editorial proposta v0.1; sujeita à revisão.

Esta orientação explica como transformar o modelo de manual técnico em um documento verificável. Ela não descreve funcionalidades de nenhum projeto específico.

Como usar o modelo

1. Faça uma cópia do modelo para o sistema, equipamento ou procedimento documentado.
2. Preencha a identificação com nome, versão compatível, repositório, ambiente, público e data da última validação.
3. Mantenha todas as seções. Quando uma seção não se aplicar, registre o motivo em vez de apagá-la.
4. Escreva comandos e procedimentos somente depois de executá-los no ambiente declarado. O que ainda não foi executado deve ser marcado como não validado.
5. Registre resultados observáveis, limitações, riscos, referências e alterações no próprio manual.

Estados e afirmações

Use o estado do material com precisão:

• Conceito: ideia ou descrição sem implementação demonstrada.
• Proposta: solução ou organização em avaliação, ainda sem aprovação definitiva.
• Protótipo: implementação experimental identificada, não presumida como pronta.
• Em teste: recurso submetido a um procedimento de avaliação com evidências registradas.
• Disponível: material ou recurso publicado com condições de uso conhecidas.
• Operacional: funcionamento confirmado no escopo, ambiente e período informados.

Um estado não deve ser promovido apenas porque o código existe ou uma página foi publicada. Diferencie sempre documentação conceitual, sistema em teste e recurso operacional.

Revisão antes da publicação

Confirme que o manual:

• identifica versão, compatibilidade, estado e ambiente;
• separa fatos verificados, propostas e limitações;
• não inventa comandos, resultados, responsáveis ou capacidades;
• não contém credenciais, dados pessoais ou segredos;
• informa como reproduzir os testes e quais evidências foram observadas;
• inclui referências versionadas e histórico de alterações;
• passa por npm test, npm run typecheck e npm run build no repositório.

Quando uma capacidade ainda não estiver comprovada, descreva-a como possibilidade, proposta ou protótipo e indique o que falta para validação. A presença do manual na documentação não transforma o recurso em disponível ou operacional.