Desenvolvimento

15 mar, 2018

4 dicas para melhorar sua documentação

Publicidade

Muitas empresas de tecnologia encontram problemas quando precisam criar e expor manuais ou tutoriais aos seus clientes. Muitas vezes isso acontece pois não há um entendimento sobre como manuais devem ser tratados e produzidos, ou até mesmo de quem é a responsabilidade de sua elaboração.

Quem nunca ouviu as frases: “O P.O que deve fazer os documentos dos produtos”; “Todo desenvolvedor deve documentar sua aplicação” ou pior: “Está em produção, quem atualiza os manuais agora?”

No meio desse troca-troca de responsabilidades, os manuais, tutoriais e portais de desenvolvedores acabam se deteriorando, o que é uma péssima imagem para o seu produto/empresa.

Para ajudar quem estiver com problemas como esses descritos, seguem algumas práticas que adotamos na Cielo e na Braspag para ajudar a melhorar nossa documentação.

1. Encontre um dono.

Um problema muito comum é saber quem dever ser o encarregado pelos documentos, não como uma pessoa que atualize, mas sim uma pessoa que é responsável pela qualidade e sucesso dessa parte do produto.

Em algumas empresas existe a ideia de que cada P.O deve organizar a documentação, mas algumas áreas como DEV e o suporte também podem ser cobradas pela obrigação de manter os manuais atualizados e práticos.

É um conflito entre a ideia de “quem específica” (quem entende como o produto funciona em todos os níveis) e “quem recebe o feedback dos clientes” (aqueles que entendem e escutam as dificuldades de quem busca informação na fonte). Isso acaba gerando uma “batata quente”, que nunca recebe a atenção necessária. Afinal, entre a decisão de documentar algo e criar uma solução, a maior parte das pessoas prioriza a segunda opção.

Uma solução é definir uma pessoa responsável pelo “desempenho” dos manuais. Pense em um P.O, que tem como seu produto os manuais. Ele fica encarregado de percorrer todos os times da empresa, mapeando como cada produto/serviço cria seus manuais e entende as dificuldades do processo.

A ideia não é que esse P.O seja o único responsável por criar e manipular os manuais, mas sim ajudar aqueles que dentro de cada time devem alterar ou criar documentos.

Essa pessoa deve analisar como usuários se relacionam com os documentos, propor soluções que tornem mais fluido o processo de atualização e recolher feedback para entender como melhorar a comunicação de cada produto com seu público alvo.

2. Trate seus “documentos” como um “produto”

Em si, produtos existem para entregar um valor que atinja ou supere a expectativa de um cliente. Pare para pensar o que torna um produto atraente. Existem vários fatores que podem aumentar e diminuir a atratividade de um produto, mas para essa discussão vamos focar em três variáveis:

  • Superam o valor que prometem;
  • Geram satisfação na usabilidade;
  • São competitivos perante concorrência.

Essas características também podem ser aplicadas para boas documentações online.

  • Documentos que “superam o valor que prometem” são aqueles que não só mostram como utilizar uma ferramenta descrita, mas apresentam soluções e maneiras de uso que o cliente não conhece ou imagina ser possível. Lembre-se que nem sempre a pessoa que lê o documento compreende a gama de soluções ou entende o mercado em que está entrando, e precisa ser “educada” sobre essas possibilidades.
  • Pense sempre nesse exemplo: A lata de leite condensado tem instruções para abertura, mas o diferencial vem na receita impressa no rótulo. Abertura da lata = uso da ferramenta; Receita no rótulo = possibilidade que o cliente pode desconhecer.
  • Documentos que “geram satisfação na usabilidade” são aqueles que possuem uma estrutura de leitura racional de acordo com o público que o lê. Não adianta ter o manual mais complexo do mundo, se ele estiver em um PDF de 500 páginas, ou detalhamentos de fluxo, sem um exemplo de código. Colha Feedbacks de usuários dos seus documentos e das suas equipes de suporte. Eles indicarão quais são os principais pontos de stress no uso da documentação.
  • Documentos “competitivos” são aqueles que estão sempre atualizados com as melhores maneiras de se passar a informação. O seu manual de integração pode ser o mais bem escrito de todas empresas de tecnologia, e ele ainda terá um apelo menor do que vídeos de 30 segundos no Youtube, que o seu concorrente lança como tutoriais. É sempre necessário entender como outras empresas lançam sua documentação, para que se possa aprender com os seus erros e acertos.

Não adianta ter uma empresa que entrega inovação e softwares de qualidade a frente da concorrência, se os desenvolvedores e clientes que vão integrar não conseguem compreender ou ter acesso a uma documentação atualizada e clara.

3. Feedback com métricas – entenda quem lê

Pronto, a documentação já tem um dono, ela já foi retrabalhada e analisada para ter uma usabilidade melhor e agora está totalmente atualizada; mesmo assim, você continua tendo problemas para fazer seus usuários e clientes utilizem/entendam seus produtos.

Isso pode ocorrer devido a dificuldade de entender como os leitores de seus documentos pensam ou quais dúvidas eles realmente possuem.

Uma das maiores dificuldades em montar documentos é se colocar no lugar do leitor. Afinal, quem monta o documento/manual deve ter um profundo conhecimento sobre a ferramenta que está sendo documentada. Esse conhecimento faz com que aquele que monta o manual possa ignorar pontos que – para o usuários – não são tão simples.

Basicamente, essa questão é a dificuldade de entender que óbvio para alguns não é tão óbvio para outros.

Isso ocorre de várias maneiras:

  1. Organização dos tópicos dos manuais: Às vezes o mercado acaba tendo um padrão que o seu manual não segue, gerando estranheza ao leitor.
  2. Uso excessivo de termos implícitos: A “abreviação” que usamos nos corredores não fazem sentido quando aplicadas a um manual, por mais que essas palavras não sejam siglas. É difícil perceber, mas existem termos que possuem um sentido implícito disfarçado de explícito, como: “Status”, “Id”, “credenciais”, “autorização X validação/autenticação (para o mercado de pagamentos)”. Sempre use nomes específicos, como “TransactionStatus” ou “RegisterID”.
  3. Forma de escrita: Pode parecer um termo subjetivo, mas até a maneira de escrever um manual pode gerar dificuldade de entendimento. É necessário entender qual o tipo de leitor acessa a documentação, senão, frases como: “Desenvolvedores preferem exemplos, e não textos descritivos” ou “Nossa documentação não é clara, apesar de ter exemplos e fluxos” irão surgir.

Para evitar esses cenários, o ideal é a aplicação de uma solução que recolha feedbacks e analise a navegação leitores.

Crie pesquisas de satisfação para entender o que mais frustra os leitores de sua documentação, aplique ferramentas de Heatmap para analisar padrões de navegação e melhorar a usabilidade do seu portal de desenvolvedores. Uma sugestão de ferramenta para esses fins é o Hotjar

O importante é ter em mente que para cada modificação feita em seus documentos ou manuais, é necessário sempre acompanhar a recepção dessa alteração com os leitores. Nada é pior do que lançar uma nova feature e perceber o número de chamados aumentando na equipe de suporte porque o manual não está claro.

4. Se possível, contrate ajuda, mas organize a casa antes.

Nem todos poderão acompanhar esse último passo num primeiro momento, mas é importante destacar que existem empresas e consultorias especializadas em organizar e gerir documentações para empresas de tecnologia, como a iMasters.

Se a gestão e acompanhamento documental é uma demanda que uma empresa acredita que pode terceirizar, então ela deve realizar esse processo. Isso permitirá um ganho de tempo e foco na criação de novos produtos.

O importante nesse passo é entender que os processos de gestão de documentações devem estar organizados antes da contratação. Caso contrário, o que ocorrerá é apenas a terceirização de uma ineficiência e não a resolução de um problema.

É necessário que haja um “dono de documentos” que lide com essa empresa parceira, para que seja definida uma estratégia clara de como manter os manuais e documentos sempre atualizados e com padrões que gerem satisfações aos leitores.