No setor de alta tecnologia, a documentação técnica costuma ser vista como um acessório. Veja como transformá-la em valor real para o produto.
Como transformar a documentação técnica em um ativo valioso
Atuo como redator técnico há mais de duas décadas e ainda me espanto com a distância entre o que a documentação técnica poderia ser e o que ela realmente é.
Nos últimos anos, tenho refletido sobre como a documentação técnica no setor de alta tecnologia pode agregar valor real ao produto, em vez de ser um mero apêndice.
Depois de testar essa abordagem em alguns produtos, os resultados me convenceram de que vale a pena seguir por esse caminho. Desde então, busco oportunidades para colocar a ideia em prática. Agora, após seis meses como redator técnico na DoiT, vou compartilhar algumas lições que aprendi e algumas reflexões novas.
O básico em primeiro lugar
Os redatores técnicos quase sempre entram depois no time de engenharia ou de produto (a depender de como a empresa enxerga o desenvolvimento de produto). Afinal, hoje em dia, todo mundo é autor/publicador. Quando você ainda está em busca dos primeiros adeptos, repositórios no GitHub, posts em blogs e discussões em fóruns podem ser caminhos mais econômicos para chegar ao público-alvo.
Só quando o produto supera essa fase inicial e está pronto para escalar é que alguém pode sugerir a entrada de redatores técnicos. Pela minha experiência, a primeira coisa que eles precisam fazer é estabelecer as regras do jogo, por meio de convenções.
Pode soar estranho colocar convenções em primeiro lugar quando se fala de um setor que se orgulha de inovação e criatividade. Mas convenções não são inimigas da inovação nem da criatividade. Seguir convenções no caminho não crítico reduz a carga cognitiva e ajuda as pessoas a focarem no que realmente importa.
As convenções na documentação técnica aparecem em diferentes formatos, por exemplo: um guia de estilo abrangente ( Google developer documentation style guide, Microsoft writing style guide) ou um conjunto simples de regras ( AWS document conventions).
Você não precisa de um guia de estilo perfeito antes de começar a documentação. Uma abordagem mais eficaz é construí-lo enquanto se familiariza com o produto. Em outras palavras, faça isso durante o seu onboarding.
Veja os passos a seguir nessa fase:
- Defina os fundamentos enquanto faz a faxina básica:
- Os títulos e cabeçalhos usam sentence case ou title case? Estão no gerúndio (verbo terminado em -ing) ou na forma base?
- Os procedimentos são escritos como listas numeradas ou como um texto corrido?
- Existe uma regra rígida sobre vírgula serial (um ótimo tema se você quiser provocar um debate entre redatores)?
- Como as interações de UI são descritas? Por exemplo: o usuário "clica", "seleciona" ou "escolhe" um botão?
- Como as capturas de tela são feitas e exibidas? E os destaques (call-outs)?
- Construa o seu guia de estilo interno ao longo do caminho:
- Pegue o melhor dos padrões do mercado e adapte às suas necessidades.
- Tenha em mente que é um documento vivo, que vai receber novos usos e termos inéditos.
Um guia de estilo interno é parte fundamental da documentação técnica. Ele não só ajuda a escalar a equipe de redatores, como também orienta outras pessoas da organização que precisam produzir conteúdo técnico, seja um rascunho para os redatores técnicos ou um post de blog.
No caminho, você pode descobrir temas ainda mais relevantes, por exemplo:
- O quanto o estilo geral é conversacional/pessoal?
- Como os vídeos são utilizados?
- Como informações sensíveis são tratadas?
- Quem são os stakeholders ou colaboradores ativos da documentação técnica?
Não se assuste com o que vai descobrir.
Como projetar a documentação técnica
Produtos de tecnologia são complexos. Eles não só usam tecnologias complicadas, como também interagem com outros produtos de tecnologia, muitas vezes de outras empresas.
Como lidar com essa complexidade ao escrever documentação técnica?
Uma resposta comum começa com: "Depende." Mas temos duas ferramentas poderosas à disposição: framework e modelo conceitual.
Framework
Um framework na documentação técnica pode ser um template ou estrutura conceitual que facilita a escrita de tópicos individuais (ou seja, tópicos que não se relacionam com outros).
A maioria dos posts de blog e páginas isoladas de documentação técnica trata de tópicos individuais e, por isso, se beneficia de um template ou framework bem definido.
Vai escrever um guia de instalação?
Pense em uma estrutura de três partes: pré-requisitos (incluindo requisitos de hardware e software), execução (os passos de instalação propriamente ditos) e verificação (conferir a versão, rodar um exemplo hello-world etc.).
Está montando instruções para consultar dados?
Lembre-se de incluir as permissões necessárias, exemplos de queries e uma explicação detalhada de entrada e saída.
Mesmo sem um template pronto, com alguma prática, dá para desenvolver um framework com relativa facilidade. Antes de entrar na DoiT, escrevi um post de blog chamado How to write (and rewrite). A abordagem sugerida ali tem a ver, principalmente, com a construção de um framework.
Veja os pontos principais:
- Use o Minto Pyramid Principle® para revelar a estrutura por trás de um texto complexo
- Crie hierarquias visuais para ajudar o leitor a navegar pelo que é complexo
- Crie agrupamentos para apoiar a jornada do usuário
Modelo conceitual
A complexidade dos produtos de tecnologia vem, em grande parte, das interações: entre componentes do mesmo produto ou entre produtos do mesmo ecossistema de negócios/tecnologia que precisam funcionar juntos para formar uma solução completa.
Em geral, você não expõe a complexidade inerente ao produto. O seu segredo pode ser interessante para os concorrentes, mas não necessariamente para os clientes.
Já as complexidades que podem gerar atrito externo merecem atenção total. Costumam ser elas que travam seus clientes e até a sua própria equipe de suporte.
No livro aclamado The Design of Everyday Things, Donald Norman explica que oferecer um bom modelo conceitual é o princípio mais importante para domar a complexidade. Concordo plenamente.
Vamos ver de perto como usar o modelo conceitual na documentação técnica, com dois exemplos do DoiT Help Center.
Funcionalidades do tipo bloco de construção
Ao falar da funcionalidade Attributions, Matan Bordo, product marketing manager da DoiT, costuma dizer que ela é "uma das funcionalidades mais aderentes do DoiT Cloud Intelligence™ quando usada corretamente". Se você chegou à conclusão de que não é fácil tirar proveito total dessa funcionalidade, te entendemos.
Attributions é uma funcionalidade do tipo bloco de construção. Como tantos outros blocos, ela faz pouco sozinha. Mas, depois que você pega a essência, é divertido trabalhar com ela.
Em uma atualização recente, revisamos a documentação dessa funcionalidade e colocamos os cenários logo no início, para que os usuários percebam do que ela é capaz antes de mergulhar em todos os detalhes de configuração.
Funcionalidades de plugin do ecossistema
Em setembro, adicionamos um artigo chamado Visualize with Grafana Cloud (contribuição do nosso CTO e cofundador, Vadim Solovey). Como você deve saber, o Grafana não é uma solução da DoiT, e sim um serviço bastante usado no Cloud Native Landscape.
Assim como no exemplo do bloco de construção, na Introdução apresentamos a razão de ser da integração e em quais aspectos ela pode beneficiar um negócio que roda na nuvem.
Seja no produto, seja no ecossistema, um bom modelo conceitual mostra a relação entre os componentes que interagem entre si, ajudando os usuários a se localizarem no domínio que escolheram.
Outros benefícios? Uma coisa é certa sobre tecnologia: os usuários são criativos na hora de usar tecnologia para resolver os próprios problemas. Com um modelo conceitual adequado, seus usuários vão descobrir novos casos de uso para o seu produto; melhor ainda, vão virar evangelistas voluntários e ajudar você a evoluir ainda mais.
É trabalho em equipe
Então, onde estamos?
Convenções e frameworks podem ser conduzidos com conhecimento genérico de redação técnica (por isso, são um bom ponto de partida para novas contratações ou redatores juniores), enquanto construir bons modelos conceituais em diferentes níveis exige conhecimento profundo do produto.
A DoiT é uma empresa de tecnologia que se orgulha da sua profunda expertise em nuvem e da mentalidade centrada no cliente. O ambiente de aprendizado é excelente. Os tópicos discutidos nos canais internos do Slack e compartilhados na wiki interna ou no StackOverflow são riquíssimos em conhecimento, e as pessoas têm prazer em compartilhar o que sabem, ajudar umas às outras e colaborar para evoluir, tanto no individual quanto no coletivo.
Como parte do time multidisciplinar de gestão de produto, os redatores técnicos atuam como parceiros de pensamento dos product managers e designers. Escrever com clareza é consequência de pensar com clareza, e isso vale ouro na hora de explicitar premissas e modelar funcionalidades de produto.
Quando discutimos o que o time de redação técnica quer alcançar, definimos como visão tornar a documentação técnica um ativo valioso no portfólio de produtos da DoiT. A chave aqui é trabalho em equipe. Documentação técnica de qualidade não é tarefa solitária dos redatores técnicos, e sim uma empreitada que o time de redação técnica da DoiT lidera junto com toda a organização.