A boa documentação é precisa, completa, compreensível e sustentável. Ele efetivamente comunica as informações necessárias ao seu (s) público (s) pretendido (s) e as ajuda a alcançar seus objetivos. Aqui está um colapso das principais qualidades:
Precisão: *
correção factual: As informações apresentadas devem ser verdadeiras e atualizadas. Informações desatualizadas ou incorretas são piores do que nenhuma documentação.
*
Consistência: A documentação deve usar terminologia, estilo e formatação consistentes por toda parte.
completude: *
abrange todos os aspectos relevantes: Inclui todas as informações necessárias para o público -alvo de entender e usar o assunto documentado. Isso pode incluir configuração, uso, solução de problemas, limitações e conceitos relacionados.
*
detalhes suficientes: Fornece detalhes suficientes para ser útil, evitando brevidade desnecessária ou verbosidade esmagadora. O nível de detalhe deve ser apropriado para o público -alvo.
Compreensão: *
clareza e concisão: Usa linguagem clara e simples, evitando jargões ou termos técnicos, a menos que seja absolutamente necessário (e depois definindo -os).
*
Organização lógica: As informações são apresentadas de maneira lógica e fácil de seguir, geralmente usando títulos, subtítulos e auxílios visuais.
*
bem estruturado: Fácil de navegar e encontrar informações específicas rapidamente (por exemplo, por meio de índices, conteúdos, funcionalidade de pesquisa).
*
Apropriação para o público: Escrito em um nível de entendimento adequado para o público -alvo (iniciante, intermediário, especialista).
Manutenção: *
fácil de atualizar: A documentação deve ser fácil de atualizar e manter -se atualizada à medida que o assunto documentado evolui. Usando um sistema de controle de versão é altamente recomendado.
*
modular e reutilizável: Os componentes da documentação podem ser reutilizados em diferentes contextos.
*
usa um formato gerenciável: Escolher o formato certo (por exemplo, Markdown, reestruturado Text, um wiki) é importante para a facilidade de edição e renderização.
Outros aspectos importantes: *
Acessibilidade: A documentação deve estar acessível a pessoas com deficiência, seguindo as diretrizes de acessibilidade.
*
Exemplos e ilustrações: Usar exemplos, diagramas, capturas de tela e outros auxílios visuais pode melhorar significativamente o entendimento.
*
Funcionalidade de pesquisa: Se a documentação for grande, fornecer uma função de pesquisa robusta é crucial.
*
Versão: Indicando claramente a versão do assunto documentado.
Em resumo, a boa documentação antecipa as necessidades de seus usuários e os ajuda a ter sucesso em suas tarefas. É um investimento que compensa os custos de suporte reduzido, o aumento da satisfação do usuário e a adoção mais rápida do produto ou sistema documentado.
