What style of documentation should product managers use in order to communicate the appropriate message?

A documentação é um dos componentes mais cruciais e subvalorizados de qualquer projeto open-source, e não deve ser encarada de ânimo leve.

De um modo geral, a maioria dos projetos open-source não recebe a atenção adequada simplesmente porque os seus autores não estão realmente interessados, não são capazes ou não têm tempo para criar um ambiente de documentação eficaz para a sua API e documentação do produto.

Embora a sua aplicação possa ser excelente, se a documentação for inadequada, os utilizadores não conseguirão beneficiar da sua utilização.

No entanto, mesmo que não tenham outra opção senão utilizá-la por qualquer motivo, não conseguirão fazê-lo com eficácia ou da forma como gostaria que o fizessem.

Compreender como produzir documentação de qualidade exige um esforço significativo, tal como analisar periodicamente outros projetos de documentação. Mas acredite em mim — como alguém que criou imensa documentação para a Docsie – se está a desenvolver código que será usado por outra pessoa além de si, e especialmente se essas pessoas são os seus clientes, o seu produto deve estar bem documentado, formatado e apresentado de forma dinâmica.

Qual é a diferença entre tutoriais, guias práticos, explicações e referências?¶

Muitas pessoas acreditam erradamente que os quatro termos se referem à mesma coisa. No entanto, expressam vários significados diferentes. Estes diferentes tipos de documentação são essenciais e têm algumas diferenças fundamentais:

Documentação de Tutoriais: Este tipo de documentação é baseada em informação orientada para formação.

Documentação de Guias Práticos/Guias do Utilizador: Os guias do utilizador explicam como resolver problemas específicos através de uma série de passos para atingir um objetivo concreto.

Documentação de Explicação: É uma documentação em formato de artigo concebida para ajudar o utilizador/leitor a obter uma compreensão mais profunda de um produto através de várias explicações e contexto.

Documentação de Notas de Referência: Esta documentação é concebida para informar o utilizador sobre a descrição de várias novas funcionalidades e utilizações. Este tipo de documentação pode ser muito "crua" na forma de documentação para programadores; contudo, também pode ser traduzida em notas de lançamento mais amigáveis que podem ser facilmente compreendidas pelo utilizador final.

Razões para produzir documentação de alta qualidade¶

Antes de prosseguir, é crucial compreender por que a escrita competente de documentação é uma necessidade muito importante, mas subvalorizada na sociedade atual. A disponibilidade de documentação extensa e bem escrita é um dos critérios mais importantes para alcançar uma adoção generalizada, particularmente em projetos open-source onde praticamente todas as ações estão disponíveis ao público e onde tais atividades desempenham um papel crucial no sucesso do projeto.

Vejamos as razões mais importantes para escrever documentação eficaz.

Permite criar uma melhor experiência de integração para os seus clientes.¶

Quando fornece documentação adequada sobre o seu produto aos seus clientes, vai ajudá-los a sentirem-se mais confortáveis com o seu produto e protegidos pelas suas diretrizes específicas. Para que isto aconteça, deve:

1. Garantir que a documentação do seu produto é visível e facilmente acessível, seja através de links na aplicação ou numa plataforma de documentação pesquisável.

2. Garantir que estão bem escritos e ajudam o cliente a encontrar a sua resposta de forma rápida e fácil

Uma dica é escrever a sua documentação apenas uma vez, e ela será consultada repetidamente quando novos clientes forem integrados pela sua empresa.

Como resultado, há menos pedidos de suporte.¶

Os clientes que leem e compreendem a sua documentação têm maior probabilidade de comprar o seu produto. Quando os clientes não conseguem compreender algo, pode ser muito frustrante, e eles podem começar a culpar o seu produto.

Alguns clientes podem contactar imediatamente a equipa de suporte se encontrarem um problema; mas, se a documentação for atrativa, facilmente acessível e compreensível, eles conseguirão resolver os seus próprios problemas sem precisar de consultar a sua equipa, o que, por sua vez, os fará sentir mais capacitados.

Ajuda a apoiar a sua própria equipa.¶

Uma base de conhecimento robusta também pode ser utilizada para ajudar os membros da sua própria equipa. A sua equipa interna deve estar informada sobre novas funcionalidades, roadmaps planeados, documentação da API e tudo o que seja necessário para manter todos na mesma página.

Instruções passo a passo sobre como escrever documentação eficaz¶

Escrever o conteúdo do documento e organizar esta atividade são tarefas completamente distintas de determinar que tom usar e como garantir que a sua documentação é compreensível. Como afirmado pela O'Reilly, existem 8 regras para uma boa documentação:

1. Criar documentação que seja convidativa para o leitor.

2. Produzir documentação completa que cubra todas as áreas do projeto.

3. Produzir material fácil de consultar rapidamente e compreender.

4. Criar documentação que demonstre como utilizar o produto através de casos práticos.

5. Escrever documentação que contenha repetição onde for necessário.

6. Escrever documentação que esteja atualizada

7. Escrever documentação para a qual seja simples contribuir

8. Escrever documentação que seja fácil de encontrar e compreender

Estes elementos estão principalmente relacionados com o conteúdo. A seguir, abordaremos o "como" estruturar esta informação em seis passos:

Decida o que deve documentar.¶

Dedique algum tempo a considerar que tipo de documentação vai produzir antes de começar: é um tutorial, um documento de referência, um manual de instruções ou uma explicação?

Note que a natureza do seu produto terá um impacto direto no tipo de documentação que será responsável por criar.

Crie uma estrutura.¶

Construa primeiro uma base para a sua documentação. Isto pode ser algo muito pequeno no início, e pode compreender apenas alguns grupos, mas com o tempo, toda a plataforma sobre a qual está a construir começará a crescer em tamanho e complexidade. Deve rever a sua estrutura organizacional regularmente.

Lembre-se que é o professor, e é, em última análise, responsável pela forma como os seus alunos aprendem na sua aula. Eles serão guiados pelas suas instruções; portanto, quanto mais tempo dedicar à estrutura, mais bem-sucedidos serão os seus alunos nos seus esforços.

Aproveite sempre técnicas multimédia eficazes.¶

Certifique-se de utilizar vídeos, desenhos e estilos variados, integrando-os diretamente na sua documentação. A Docsie permite incorporar qualquer um destes elementos na nossa plataforma para facilitar este processo.

Não só ajudarão os consumidores a compreender melhor a informação que transmite, como também proporcionarão uma excelente Otimização para Motores de Busca, o que levará a um maior número de leads de alta qualidade graças à sua documentação dinâmica.

Certifique-se de que é pesquisável.¶

Existem diferenças nas capacidades de pesquisa de diferentes plataformas de base de conhecimento — algumas oferecem apenas pesquisa básica sem possibilidade de detalhar em segmentações (o que é tecnicamente aceitável se não tiver milhares de ficheiros), enquanto outras oferecem opções de consulta que permitem pesquisar não apenas em documentos, mas também em nomes de utilizadores.

No entanto, há uma coisa que é fundamental: deve utilizar uma ferramenta que permita pesquisar rapidamente. Uma funcionalidade de pesquisa incluída na aplicação facilita a procura de ficheiros e a sua visualização sem sair da aplicação.

A Docsie permite ter uma navegação dinamicamente pesquisável para aceder facilmente à informação.

Esforce-se constantemente por melhorar e atualizar¶

Criar e utilizar documentos é difícil porque são rapidamente esquecidos pelas pessoas que os geraram ou beneficiaram deles. Os documentos também enfrentam vários desafios ao longo do seu percurso.

Com o passar do tempo, a estrutura de pastas assume a aparência de um cemitério, pois a documentação mais antiga tende a permanecer numa posição inferior no ecrã do monitor.

Portanto, certifique-se de revisitar a sua documentação antiga e fazer melhorias, e incentive os seus colegas a fazerem o mesmo de vez em quando. A Docsie permite criar atualizações através do nosso sistema avançado de versionamento, que é simples e fácil de usar.

Considerações finais:¶

Quer saber mais sobre como escrever documentação eficaz? Para profissionais de documentação de software, existe uma grande quantidade de blogs e informações disponíveis aqui.