Close

Como criar documentações melhores

Você acabou de começar um projeto e agora precisa entregar uma documentação (p*tz!).

Parece assustador no início? Claro — mas a gente está aqui para ajudar! Abaixo, você encontra a documentação sobre a documentação — um guia passo a passo com dicas profissionais—para guiar você pelo processo.Vamos lá!


Ok, por que devo me importar?

Em termos simples, a documentação ajuda as pessoas a fazer o que elas precisam fazer. Porém, assim como a maioria das coisas que são extraordinárias de um jeito inexplicável, ela faz muito mais do que apenas ajudar as pessoas a botar a mão na massa. A documentação ajuda usuários e equipes a:

Utilizar menos energia mental

Trabalhe sem ter que pensar muito e fazendo o mínimo de esforço possível.

Ter consistência

Garanta que as mesmas informações, processos e planos sejam consumidos pelo público com consistência.

Minimizar a carga de trabalho

Integre colegas de equipe com rapidez e eficiência para que eles comecem a trabalhar de imediato.

Melhorar a imagem de marca da empresa

Mostre como você trata os clientes externos e funcionários internos sendo solidário e prestativo.

Se você não oferece valor, ninguém presta atenção. É você quem deve moldar o que os leitores pensam sobre as informações que você oferece a eles e ensinar por que essas informações importam.

O que é documentação?

A documentação é tudo que você pensa que é: um conjunto de documentos. Uma bússola para o usuário final médio. Um esquema tático para o engenheiro de software em você. Em um espaço mais técnico, a documentação é, na maioria das vezes, textos ou ilustrações que acompanham uma peça de software. Esses documentos servem como guia de referência, explicando como o software funciona, é operado e como deve ser usado. As equipes de software podem consultar a documentação ao falar sobre os requisitos do produto, notas da versão ou especificações de design. Equipes técnicas podem usar a documentação para dar mais informações sobre códigos, APIs e registrar os processos de desenvolvimento dos softwares. Externamente, a documentação muitas vezes adotar a forma de manuais e guias de usuários para sistemas administrativos, equipes de suporte e outros usuários finais.

Toda documentação deve buscar realizar duas coisas principais:

1. Informar os usuários

2. Ajudar os usuários a realizarem as coisas com sucesso

Ao iniciar qualquer documentação, comece definindo o tópico de interesse, objetivo ou meta para ajudar o público a entender o que eles estão lendo logo de cara.

Tipos de documentação

Como já mencionado, as documentações podem ser de todas as formas e tamanhos, internas ou externas. Diferentes tipos de documentações precisam de diferentes vozes, tons, formatação, contribuidores, público e conteúdo. Os tipos mais comuns são:



Documentação interna
team-documentation-illustration

Documentação da equipe

A documentação de equipe ajuda a esclarecer o trabalho que está sendo feito para que as equipes possam, bem, trabalhar em equipe. Esses documentos podem ser do formato de planos de projetos, cronogramas de equipes, relatórios de status, anotações de reuniões e qualquer outra coisa de que a equipe precise para trabalhar com funcionalidade e eficiência. Esse tipo de documentação é aprofundado, o que garante que todo mundo esteja na mesma página.

reference-documentation-illustration

Documentação de referência

A documentação de referência educa a empresa sobre tópicos, processos e políticas importantes. Podem ser políticas criadas pelo setor de RH, processos jurídicos para a contratação de fornecedores externos ou artigos de passo a passo sobre como definir os benefícios da empresa. Lembre que a documentação de referência é escrita por um grupo pequeno de pessoas para um público grande e variado, então conteúdos rápidos e acessíveis são importantes.

project-documentation-illustration

Documentação de projeto

A documentação de projeto é, claro, específica para cada projeto e oferece a estrutura necessária para o desenvolvimento de produtos. Estão incluídas propostas, documentos de requisitos de produtos, diretrizes de design ou esboços, roteiros e outras informações relevantes necessárias para o desenvolvimento, com contribuições de gerentes de projeto, engenheiros, designers e muito mais.



DOCUMENTAÇÃO EXTERNA
system-documentation-illustration

Documentação de sistema

A documentação de sistema contém os códigos, APIs e outros processos que informam aos desenvolvedores e programadores quais tipos de métodos e funções podem ser usados para desenvolver softwares específicos, assim como suas limitações e requisitos. Snippets de código, como, por exemplo, chamadas e respostas de API, são essenciais para esse tipo de documentação.

end-user-documentation-illustration

Documentação de usuário final

A documentação de usuário é muitas vezes o tipo de documentação mais visível. Ela deve ser fácil de ler e de entender e deve ser atualizada com cada nova versão de software. Ela adota a forma de documentos "Leia-me", guias de instalação, guias de administrador, bases de conhecimento de produtos e tutoriais (a parte mais útil de todas). E, assim como a documentação de referência, é produzida por um pequeno grupo de criadores e destinada a um grande público de consumidores, então o conteúdo rápido e acessível é importante.

Incluir exemplos na documentação agrega muito valor para o público. Eles servem como ponte para ajudar a entender conceitos e ideias e garantir ao leitor que você sabe mesmo do que está falando.

Como criar uma documentação

O objetivo final é garantir que a documentação seja útil para o leitor. Abaixo, a gente oferece um tutorial para a sua documentação para ajudar a facilitar um pouco essa tarefa.

1. Pesquise

O que os usuários precisam saber sobre o seu produto, projeto ou API? Use a ferramenta de análise para ver o que está sendo pesquisado, entre em fóruns de comunidades e grupos de discussões on-line e conduza pesquisas de usuário e testes de usabilidade. Também é importante conhecer o produto, saber responder às dúvidas dos usuários e explicar novos recursos e fluxos de trabalho com facilidade.

2. Apenas comece

Comece dizendo com clareza o que vai ser apresentado na documentação e por que ela vai ser útil para o leitor.

3. Foque nos dados

Crie esboços e elabore seu conteúdo. Escreva com voz e tom adequados (seja natural!) para o público e seja consistente e conciso com a sua linguagem. Transmita informações importantes com clareza.

4. Formate

Organize sua página para que seja fácil de acompanhar do início ao fim. Exclua o que não for essencial e divida conteúdos longos com elementos visuais como diagramas, capturas de tela e imagens.

5. Revise

Solicite revisão e feedback do conteúdo. Garanta que os revisores entendam o objetivo da documentação. Assim, vai ser mais fácil detectar linguagem confusa ou as passos que faltam.

6. Publique

Após as revisões e edições, está tudo pronto para lançar! Publique seu trabalho e fique atento aos feedbacks e comentários. Uma documentação não é algo que você publica e esquece!

Lições de ouro

Como você pode ver, a documentação não é apenas um monte de instruções e palavras juntas. Há um método para toda essa loucura, amigos. Lembre-se desses princípios direcionadores antes, durante, enquanto você dorme e depois de criar a documentação:

Seja breve

A documentação deve ter a quantidade certa de informações para que as pessoas trabalhem sem precisar criar tickets de ajuda. Ofereça aos leitores pontos-chave do texto e a opção de ver mais informações.

Recursos visuais são fundamentais

Elementos visuais são essenciais para a compreensão. O design de produtos, exemplos de códigos, demonstrações no produto, capturas de tela e tutoriais em vídeo são fundamentais para ajudar os leitores a compreender todo o conceito, o que fazer ou como fazer. Também tenha em mente o layout, a legibilidade e a facilidade e acessibilidade de leitura de fragmentos de texto.

Conheça seu público

Tenha a perspectiva do usuário. Conheça o leitor, trace o caminho do usuário do seu produto e da sua documentação. Essas técnicas devem sempre guiar como e o que você escreve.

Comece a trabalhar rapidamente com sucesso

A melhor documentação é aquela que é clara, concisa, informativa e, o mais importante, a que agrega valor para o público. Explore um software de colaboração de equipes como o Confluence para a sua documentação e para passar menos tempo com buscas e mais tempo fazendo as coisas acontecerem.

Saiba mais