Estratégias para escrever documentação técnica eficaz

Tenho feito redação técnica de um tipo ou de outro desde 1999, quando fazia controle de qualidade para a filial de P&D da Altec Lansing em Kfar Saba, Israel. Naquela época, lançávamos dispositivos inovadores relacionados a áudio, como (suspiro) dispositivos de áudio USB que funcionavam no Windows ME e 2000. Eles apresentavam bugs e configurá-los não era tão simples como é hoje.

Precisávamos de documentos.

Tínhamos alguns obstáculos que os usuários precisavam superar e precisávamos de uma maneira de documentar o que eram, quais eram os casos extremos e como diagnosticar e corrigir todas essas coisas. Ele precisava ser bem empacotado, formatado de forma limpa e acessível aos usuários que instalaram nosso aplicativo auxiliar. Encontrei o aplicativo Robohelp, usado para criar aplicativos de ajuda padrão no Windows, e adicionei um arquivo de ajuda à nossa instalação.

Durante nosso processo de controle de qualidade, identificaríamos os problemas, documentaríamos o que consideramos importante e organizaríamos tudo no arquivo de ajuda que acompanha o dispositivo. Eu tinha 19 anos na época e não tinha nenhuma experiência com essas coisas, e foi um processo imensamente ingênuo. No entanto, parecia a coisa certa a fazer pelos nossos usuários, e meu gerente não me disse explicitamente para não fazer isso.

Já se passaram 24 anos e, desde então, fiz documentação para vários projetos. A escala cresceu e a forma como vejo esses tipos de projetos mudou substancialmente.

Tenho algumas ideias sobre o que constitui bons documentos e adoraria compartilhá-las com você, se estiver interessado.

Conceito Básico de Documentação

Gostaria de começar com um conjunto de regras mais concretas que acredito serem críticas para o sucesso de um produto de documentação.

• Os documentos devem usar palavras pequenas para descrever grandes ideias . Portanto, não use palavras floridas ou frases complexas para descrever o que pode ser dito em termos mais simples. Você perderá usuários ao longo do caminho e isso não vale o ego do seu escritor.

• Os documentos devem contar uma história quando você puder , porque um conjunto pessoal e identificável de tarefas que contam uma história será mais envolvente e memorável para o usuário do que um conjunto abstrato de instruções.

• Os documentos devem ser pesquisáveis - porque, falando sério: isso é óbvio. Se não for fácil encontrar itens em seus documentos, seus usuários não encontrarão o que precisam.

• Os documentos quase sempre fazem parte de uma estratégia maior – e isso é especialmente verdadeiro quando se trata de produtos de software. Isso aborda o tópico mais amplo de defesa do desenvolvedor, mas em resumo: seus documentos devem ser apoiados por tutoriais em vídeo, exemplos reais de uso e suporte técnico ao vivo.

• Os documentos devem ser testados - porque você pode ter certeza de que está tudo certo, mas sem usuários reais, como acontece com qualquer outro produto, você não terá certeza. Teste e teste novamente.

  
  

Documentos holísticos são produtos bem projetados

Quando você aprende uma nova linguagem de programação , os conceitos e ideias dessa linguagem fluem para o seu pacote de truques para solução de problemas. Isso faz de você um desenvolvedor de software melhor e, no final das contas, você cria um software melhor porque é mais consciente e capaz.

Minha carreira tem sido complicada e incluiu muito design de produtos de software, desenvolvimento de software, suporte técnico e defesa do desenvolvedor. Cada disciplina influenciou a forma como penso e abordo os outros.

Quando abordo um projeto de Redação Técnica, é com essa visão ampla do que um usuário vai precisar. Acho que essa é a maneira certa de pensar sobre documentos: de forma holística. Documentos não são algo bem definido e para criá-los você precisa ser flexível.

Para mim, isso significa que você precisa pensar nos usuários de todos os ângulos possíveis. Você não pode considerar nada garantido ou irá decepcionar algum grupo de usuários de uma forma que impactará negativamente sua marca, seu produto ou seu negócio de uma forma que será difícil de reverter.

Seus documentos costumam ser uma experiência decisiva para seus usuários.

Se você fizer um bom trabalho, seus usuários usarão seu produto com sucesso e se tornarão campeões de sua marca. Do contrário, eles provavelmente nunca mais usarão seu produto porque seus documentos deixaram um gosto ruim em suas mentes. Eles também informarão outras pessoas. O bom marketing começa aqui, então tenha isso em mente.

Fazendo bons documentos

Fazer bons documentos significa simplesmente que você deve abordar a criação de seus documentos como faria com qualquer outro processo de produto.

Você precisa:

• Saiba por que você está criando seus documentos
• Saiba quem é o seu público-alvo
• Saiba quais são seus pontos fracos
• Melhore seus documentos ao longo do tempo

Vamos dar uma olhada em cada um deles.

Saber o porquê de seus documentos costuma ser uma pergunta e uma resposta muito diretas definidas superficialmente. Você está criando documentos porque, do contrário, os usuários passarão despercebidos e deixarão de usar seu produto. Em um nível mais profundo, há uma resposta específica para o seu caso de uso. Tem uma ferramenta de desenvolvedor? Esse é um conjunto de respostas. Tem uma ferramenta de design de varejo? Tem um produto SaaS de contabilidade? Tem cafeteira automática? Todos esses são conjuntos de respostas separados.

A forma dos seus documentos é descrita por quem irá utilizá-los. Está on-line? Ele vem com um aplicativo? É impresso? Cada base de usuários precisará de algo mais e você deve deixar claro desde o início quem eles são.

Seu trabalho é descobrir o que é difícil para cada um de seus usuários e elaborar seus documentos para canalizá-los por meio de conteúdo informativo que resolva seus problemas específicos.

Mais importante ainda, você precisa saber que provavelmente não acertará na primeira vez. Isso significa que seus documentos precisam ser mantidos e atualizados à medida que seus produtos crescem e mudam com o tempo. Esperamos que isso seja feito dentro de alguma estrutura que permita uma comunicação fácil com os usuários que você está tentando ajudar. Você tem que conversar com seus usuários, ouvir suas necessidades e tentar usar seus documentos para tornar a experiência deles com seu produto melhor.

Seus documentos são parte integrante do seu sucesso

Resumirei simplesmente sublinhando o quão extremamente importantes são os documentos. Sem eles, seus usuários estarão sozinhos e terão que se defender sozinhos.

Isso sempre significará menos casos de sucesso, visões mais ruins do seu produto dentro do seu ecossistema, mais desenvolvedores ou usuários insatisfeitos e um impacto negativo na sua marca ou empresa.

Os documentos são um subproduto sério por si só, são um investimento e devem fazer parte de sua estratégia de produto mais ampla.