Dicas para Escrever uma Boa Documentação Para Seu Produto

Documentação técnica. Duvido que seja algo que qualquer um de nós classifique como gênero favorito, seja para escrever ou para ler. Mas é uma dessas necessidades que muitas vezes não gostamos, mas aceitamos que temos que enfrentar para resolver um problema ou quando temos que escrever para explicar um produto técnico.

Uma boa documentação é difícil de escrever. Existem várias formas que os documentos técnicos podem tomar: visões gerais ou de alto nível, tutoriais passo-a-passo, ou documentos gerados automaticamente. Adicione isso à variedade de usuários que possam precisar da sua documentação – suas necessidades diferenciadas, conhecimentos técnicos, estilos de aprendizagem – e você provavelmente irá descobrir que não existe nenhum formato único que irá funcionar com todos.

Escrevendo para o Público Certo

A primeira coisa que você precisa para considerar quando for escrever sua documentação para seu projeto é seu público. O usuário final vai querer uma documentação que seja essencialmente instrucional – um tutorial. Embora alguns conceitos técnicos possam ser citados (e explicados), a ênfase deve ser na interface. Um programador que esteja olhando a documentação vai querer obter informações adicionais: detalhes técnicos de como funcionam os elementos do programa, onde acontecem as ações no código, e, se aplicável, como estender o código. Ao escrever para um público, não se deve impedir de escrever para outros, mas você deve considerar documentos distintos – por exemplo, a documentação técnica do usuário e a documentação técnica do técnico.

Tipos de Documentação

No guia para escrita de bons documentos de Jacob Kaplan-Moss, ele aponta três categorias para as documentações: tutoriais, guias de tópicos, e guias de referência.

Tutoriais: Tutoriais são importantes, pois são muitas vezes uma primeira impressão quando alguém usa uma nova ferramenta de tecnologia. Existem uma série de ferramentas para ajudá-lo a fazer bons tutoriais. Mas se você está escrevendo um, Jacob recomenda que os tutoriais sejam rápidos e fáceis – mas não tão fáceis – e que demonstrem como é o seu projeto. Exemplo: o guia do usuário da Anthologize , uma ferramenta blog-para-ebook recém lançada. Observe as imagens que acompanham cada passo.

Guias de Tópicos: Nas palavras de Jacob, eles são “a carne da sua documentação.” Enquanto um tutorial fornece uma introdução aos conceitos de alto nível, os guias de tópicos são para aqueles que querem aprofundar mais. Seu objetivo principal deve ser a compreensão. Conforme Jacob observa, os livros muitas vezes ofuscam a documentação oficial, o que é lamentável já que esses últimos podem ser facilmente atualizados. Exemplo: documentação do Django – tudo o que você precisa saber sobre o Django.

Guias de Referência: Os guias de referência são projetados para os usuários que compreendem um pouco dos guias, mas estão procurando por informações mais avançadas. “Esses guias devem ser feitos para aqueles que já sabem utilizar a API, mas precisam pesquisar por argumentos exatos de algumas funções, ou como uma configuração particular influencia o comportamento, etc. É importante ressaltar que o material de referência não é de modo algum um substituto para os tutoriais e guias!” A documentação gerada automaticamente é um começo, mas sem uma escrita, edição e organização adicional, é improvável que essa documentação responderá as perguntas dos usuários.

E só porque é uma “escrita técnica” não significa que você deva abandonar a gramática e a ortografia, e quem sabe uma linguagem poética? Bem, ter cuidado com a gramática e a ortografia já está de bom tamanho.

0 responses to “Dicas para Escrever uma Boa Documentação Para Seu Produto

  1. Excelente artigo.

    O Django também tem um conceito interessante: DDD (Documentation Driven Development) – onde a documentação de uma feature vem antes da sua implementação (processo parecido – porém tecnicamente muito diferente – do Test/Behaviour Driven Development).

    O Django tem uma documentação invejável em vista da doc de outros projetos principalmente por causa do DDD.

  2. Excelente artigo.

    O Django também tem um conceito interessante: DDD (Documentation Driven Development) – onde a documentação de uma feature vem antes da sua implementação (processo parecido – porém tecnicamente muito diferente – do Test/Behaviour Driven Development).

    O Django tem uma documentação invejável em vista da doc de outros projetos principalmente por causa do DDD.

Deixe uma resposta para Herberth Amaral Cancelar resposta

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *