Elaborar uma documentação técnica de qualidade nem sempre é uma tarefa simples ou fácil. Isso porque não existe um conjunto de instruções fechado que pode ser impresso e nunca mais precisará ser revisado.
A tecnologia muda constantemente e geralmente a documentação de um time ou projeto pode ficar defasada rapidamente, se não houver o papel de Technical Writer (TW) olhando para este tema, pois o código em si tem um crescimento dinâmico e acelerado.
Por isso mesmo, o primeiro trabalho de Tech Writers é definir escopo e prioridades ao trabalhar com qualquer tipo de documentação.
No contexto de tecnologia, documentações têm múltiplas funções:
- Formalizar processos e sistemas;
- Fornecer base de estudo;
- Ajudar pessoas (independentemente de sua função) a responder suas dúvidas.
Em todos os casos, tanto quem escreve quanto quem consome recebem o benefício com a produção do material. Ter uma boa documentação para o seu time, principalmente se tratando de projetos de código aberto, é um diferencial importante que pode influenciar positivamente na popularização da sua aplicação ou biblioteca.
Antes de tudo, você sabe qual é o exato papel de Tech Writer?
Technical Writer ou TW é a pessoa responsável exclusivamente por organizar, direcionar, revisar e manter a doc atualizada.
O mercado de tecnologia em geral tem como foco o reuso e transparência. Para que isso possa acontecer em todos os níveis, é fundamental que cada squad disponibilize informações importantes, de forma estruturada e com qualidade através da documentação. Não é só um textinho, é arquitetura da informação, jornada de uso, acessibilidade e outros fatores.
Ter uma pessoa TW na sua squad vai te colocar à frente da modernização, reduzir os chamados, trazendo autonomia, agilidade e tornando o conhecimento acessível.
Inclusive, nosso time de Tech Writers conversou um pouco sobre sua função com colegas de UX em um episódio do Zupcast. Vale ouvir!
Os princípios da produção de conteúdo, as etapas de cada ciclo e como começar
Se você quer saber mais sobre este tema, confira a seguir um miniguia que fornecerá diretrizes para escrever documentações destinadas às pessoas desenvolvedoras, de maneira clara e consistente. Use as orientações aqui apresentadas para deixar sua doc ainda melhor.
Pensando no modelo inner source, este guia também é colaborativo. Por isso, se você tiver alguma sugestão, é só fazer um comentário neste artigo.
Vamos às sete dicas fundamentais para escrever uma boa documentação!
1. O começo de uma documentação técnica de qualidade
Documentar é compartilhar conhecimento de forma transparente e acessível para todas as pessoas. Uma boa documentação é viva, sempre atualizada com o produto e serviço, sendo pensada e criada desde os primeiros insights e não apenas no final.
Ela ajuda a economizar tempo de quem busca uma informação, reduzindo os chamados de suporte. Dessa forma, a documentação dentro de uma cultura colaborativa tem papel fundamental para profissionais de desenvolvimento e a pessoa usuária final.
Para produzir uma boa documentação, independentemente da ferramenta (embora a escolha da ferramenta adequada também seja importante), tenha sempre em mente os princípios norteadores de uma boa documentação: clareza, objetividade, organização e simplicidade.
Além disso, é necessário ter atenção a alguns pontos para que o conteúdo adquira organização, fornecendo uma linha de construção de conhecimento capaz de promover a autonomia e satisfação para quem consome a documentação. Dentro dos principais pontos, podemos citar: mapeamento do conteúdo, seleção de informações, acessibilidade e disponibilização das informações.
2. Entenda quais são os princípios da produção de conteúdo
Uma boa documentação deve sempre prezar por eficiência, objetividade, organização, consistência e inclusão. Por isso, para nortear a produção de conteúdo, nos orientamos pelos seguintes princípios que conduzem uma documentação para a excelência:
- Clareza: produza um conteúdo compreensível e fluido. Para isso, lembre-se da coerência e da coesão das informações.
- Objetividade: produza um conteúdo direcionado. Faça um levantamento das informações pertinentes e necessárias e escreva sem rodeios. Informações interessantes, porém, extras, devem ser agrupadas em uma seção de conhecimentos adicionais.
- Organização: as informações devem ser organizadas de maneira que seja possível construir uma linha de conhecimento lógica, portanto, faça um levantamento de tudo que deve ser documentado e organize a hierarquia das informações, prezando por padronizações.
- Simplicidade: mantenha a simplicidade. Lembre-se que o foco da comunicação é a compreensão da mensagem. Não utilize vocabulário desnecessário, nem recursos excessivos que poluem as informações e atrapalham a compreensão.
- Atualização contínua: um produto ou serviço só está pronto de fato se puder ser utilizado. Para tanto, a documentação é vital, já que ela norteia o uso e ajuda a tirar melhor proveito do que foi recebido. Ela deve ser criada logo na primeira sprint e estar pronta na última, sendo constantemente atualizada.
3. Mapeie o que será documentado
Antes de iniciar uma documentação ou uma contribuição, é necessário compreender o que precisa ser documentado e verificar se já existem informações a respeito do que você pretende documentar.
Entender o que de fato precisa ser documentado e qual é a sequência correta das informações é um grande passo para a construção de uma estrutura de documentação. Esse passo ajuda inclusive a escolher uma ferramenta de documentação mais adequada ao tipo de conteúdo que será exibido.
Além disso, é necessário verificar quais conteúdos estão atualizados e se existem informações “espalhadas” em diferentes bases. Isso também é importante nos cenários em que existem documentações legadas. Assim, fica mais fácil levantar as informações que deverão ser produzidas e/ou atualizadas.
O que fazer com a documentação legada?
Muitas vezes, os times e projetos já possuem uma documentação, oriunda de outras versões ou não, com diversas origens.
O mapeamento das informações é a principal etapa para recuperar o conhecimento, principalmente quando está somente “na cabeça das pessoas”. Nesse caso, é necessário criar ações para registrar e transformar o conhecimento em insumo para a documentação técnica.
Para conseguir iniciar esse processo, faça entrevistas com as pessoas que são referência em determinado conhecimento ou até mesmo agendas de treinamentos com o time, ajudando no processo de recuperação e registro do conhecimento.
A priorização das entregas também é um passo importante, a resposta do “por onde começar” deve estar alinhada com as respostas sobre quais dores o time pretende eliminar com a documentação.
Por exemplo, seu time pode ter o foco de diminuir acionamentos de dúvidas, gerando economia de recursos (tempo e capital humano), foco em melhorar o entendimento do produto pela pessoa usuária, entre outros.
Nos cenários de documentações espalhadas e em diferentes extensões (Word, PDF, e-mail), o ideal é centralizar esse conteúdo em um único local, para facilitar o refinamento e a atualização das informações.
Em contextos colaborativos e evoluídos, é possível estabelecer regras e padrões que garantam que a documentação esteja organizada, porém tenha atenção para que isso não se torne um bloqueio para as contribuições.
4. Selecione e organize as informações
Depois de averiguar todas as informações relacionadas ao tema, verifique se o conteúdo está atualizado. A documentação técnica é reflexo do produto, portanto, a informação da doc deve ser compatível com a versão do produto.
Este é o momento de pensar no formato em que o seu conteúdo será exposto. Para isso, organize de maneira que constitua um sentido lógico para construção do conhecimento. Para isso, pense na jornada da pessoa usuária com o produto, informe a sequência de atividades, com começo, meio e fim.
Lembre-se que para estabelecer essa construção lógica, caso as informações estejam espalhadas em diferentes bases, o ideal é promover a centralização do conteúdo, evitando a duplicidade de informações.
Organize também o conteúdo em tópicos que caminham do global para o particular. Em cada tópico, preze por definições claras e objetivas, sem esquecer do que é essencial para a pessoa usuária.
De maneira geral, as documentações técnicas conseguem responder às seguintes questões (dependendo do objeto de documentação):
- O que é?
- O que faz (para que serve)?
- Como funciona?
- Como utilizar?
Se você tiver informações extras que considera interessantes, coloque-as em uma página específica, com um título que demonstre que aquilo é um conteúdo extra, por exemplo uma seção: “Para saber mais”.
5. Comece a escrever sua documentação técnica
Depois de reunir todo o material, ler, organizar e estruturar, é hora de colocar o conteúdo na sua documentação, pensando em como a pessoa usuária consumirá estas informações, seja em texto, imagem ou vídeo.
Escreva sempre com foco no seu público-alvo, ou seja, adeque a linguagem a quem vai ler. Mesmo que a pessoa leitora seja da área técnica, descreva cada passo de forma integral, sem pular etapas por supor que quem está lendo sabe o que fazer. Detalhar os processos evita erros mínimos, que se tornam chamados de pelo menos 30 minutos.
Sempre que possível, utilize imagens ilustrativas, gráficos e fluxogramas que auxiliem no entendimento do seu conteúdo. O recurso vídeo é muito interessante, porém, lembre-se que eles devem ser curtos e idealmente diretos, sem “erros” de gravações, memes e afins. Caso o conteúdo do vídeo seja extenso, quebre em conteúdos menores.
Você está escrevendo para outras pessoas, então tenha foco no seu público-alvo: defina um idioma e não esqueça de utilizar a linguagem inclusiva e recursos de acessibilidade para atingir o maior número de pessoas.
6. Pense na acessibilidade
Uma documentação acessível elimina as barreiras que poderiam impedir todas as pessoas de acessar o conteúdo ali disposto. Dessa forma, sua documentação deve ser acessível a todas as pessoas usuárias, sem restrição.
Por isso, é fundamental que você tenha atenção a alguns pontos durante a sua escrita:
- Descrição das imagens: todas as imagens que contém informações importantes para quem está lendo – ou seja, que não são apenas decorativas – devem ter uma descrição em texto alt ou com a tag #DescreveAí, logo abaixo das mesmas.
- Transcrição dos vídeos: se for apresentado vídeo, ele deve ter legenda em português ou sua transcrição corrigida na íntegra.
- Uso de templates acessíveis: a escolha do template influencia diretamente na qualidade da acessibilidade, facilitando o uso ou criando barreiras.
- Padronização da escrita: uma escrita padronizada ajuda na compreensão do conteúdo, portanto utilize as boas práticas. Aqui na Zup, nós temos um Manual de Redação e Estilo que pode ser um excelente guia nesse sentido.
- Uso moderado de distratores: evite o uso de elementos que causem distração durante a leitura, que não sejam necessários, como imagens animadas, vídeos sem relação com o conteúdo e afins, melhorando a usabilidade para pessoas neurodivergentes.
- Criação de fluxogramas acessíveis: nós recomendamos a utilização do draw.io para a criação de fluxogramas acessíveis para todas as pessoas, ao invés de imagens ou capturas de tela de fluxogramas.
7. Como disponibilizar sua documentação técnica
Para disponibilizar sua documentação, escolha uma ferramenta adequada, levando em consideração aquelas já utilizadas pelo time, tanto para desenvolvimento quanto para facilidade de ações.
Algumas ferramentas indicadas para documentação são:
Confluence
O Confluence é uma das ferramentas de gestão de conteúdo e colaboração simultânea mais utilizadas no mercado. É fácil de ser utilizada e oferece diversas opções de macros e plugins customizáveis.
Entretanto, nem sempre as equipes se atentam para a hierarquia e padronização do conteúdo, o que dificulta a localização e a divulgação de documentações relevantes em determinados contextos.
GitHub
O GitHub e o GitLab são ferramentas que utilizam o sistema de controle de versão Git, permitindo a agilidade e colaboração simultânea no desenvolvimento de software. Elas podem ser integradas a algum conversor de HTML estático para publicar documentações em formato de webpage ou website.
O uso de uma mesma ferramenta para a construção do código e da documentação, é uma excelente estratégia para a adoção da filosofia Docs as Code, visando a aproximação e maior colaboração dos times com a documentação.
Dicas de legibilidade
Procure manter um padrão de fonte, imagens e tabelas nos conteúdos disponibilizados. Siga também a hierarquia de headings (títulos e subtítulos) proposta pela ferramenta escolhida, lembrando que as informações mais importantes (ou globais) têm um heading maior e a sequência de tópicos escalam para os headings menores.
Exemplo:
História do Mundo (H1)
História do Brasil (H2)
A história de São Paulo (H3)
Conclusão
Por fim, cuide de sua documentação técnica, para que esteja sempre atualizada. O ideal é que cada equipe tenha ao menos uma pessoa Tech Writer, responsável por zelar pela documentação, para que ela seja de fato uma base de conhecimento consumível e agregadora de valor.
Para conhecer mais sobre o time de Tech Writers da Zup e documentação técnica de qualidade, continue acompanhando nossos conteúdos e comente abaixo para tirar suas dúvidas sobre o tema.
Além disso, nós, autoras do artigo, estamos disponíveis assim como nosso time de Tech Writers para ajudar quem deseja conhecer mais sobre o tema!
*Conteúdo aproveitado/inspirado da Squad Doc – Doc Advocates do Itaú
*Conteúdo elaborado por Elen Baldini, Gisele Rosati e Sherillyn Martins
