Materiais gratuitos

Como criar uma boa documentação de API

Você criou uma nova API para o seu ERP e quer fazer uma boa documentação? Então confira alguns aspectos que merecem a sua atenção durante esse processo.

Por Time Juno
Como_criar_uma_boa_documentacao_de_API
Tempo de leitura: 5 minutos

Escrever uma boa documentação de API é importante. No passado, os criadores de integrações não costumavam dar muita atenção a esse detalhe. Porque, vamos combinar: é muito mais interessante criar um código do que escrever uma boa documentação.

Criar esses materiais exige que o dev se coloque no lugar do consumidor, pense como um “leigo” e preveja quais podem ser as dificuldades que o potencial usuário vai encontrar no início do processo.

Essa tendência das empresas darem atenção à documentação — juntamente com o aperfeiçoamento de ferramentas que ajudam nesse processo — se dá porque ela é importante para a adoção da solução.
como criar uma boa documentação de API
Os documentos são o primeiro contato com o consumidor e se eles forem complexos as chances de uma integração diminuem consideravelmente. Além disso, contar com uma boa documentação garante que os clientes sejam mais autônomos. Isso diminui o trabalho do time de suporte.

Você criou uma nova API para o seu ERP e quer fazer uma boa documentação? Então confira alguns aspectos que merecem a sua atenção durante esse processo.

Melhores práticas para realizar uma boa documentação:

Entenda quem vai usar a sua documentação

Antes de começar a sua documentação é fundamental entender quem exatamente vai utilizá-la. Dependendo do tipo de integração, ela precisa ser feita por desenvolvedores que têm mais conhecimento. Nesse caso, ela pode usar uma linguagem mais focada em quem é da área.
Caso a sua API seja para um público mais leigo, é importante ao máximo evitar jargões e ser bem claro em cada passo do processo. Para isso, entenda claramente quem vai se beneficiar dos seus documentos.

Facilite o primeiro contato com a documentação

Você passou dezenas de horas desenvolvendo a sua API, então conhece a fundo cada um dos detalhes dessa funcionalidade. Já o seu usuário, não. Portanto, capriche na introdução da sua documentação, garantindo que os seus usuários tenham uma visão clara e rápida a respeito da solução.
A partir do momento que você deixa as informações claras desde o começo, o número de chamados no seu suporte diminui, visto que até quem está começando na sua API entende a estrutura. Isso é excelente para o seu consumidor, que não precisa se estressar esperando respostas, e para o seu time, que não perde tempo explicando detalhes simples.
A forma que a sua documentação é apresentada também é importante. Ofereça logo de cara o básico, para que o desenvolvedor possa começar a usá-la. Só depois disso traga dados sobre outras features e SDKs.

Guia rápido para quem é novo

“Por onde eu começo?” Essa é a sensação que muitos clientes têm quando se deparam com a necessidade de fazer uma integração via API. Portanto, a sua documentação deve trazer um breve manual com os passos para completar as tarefas mais comuns. Esse guia também pode trazer informações sobre o domínio e o contato de alguém do seu time que pode auxiliar em situações especiais.

Navegação inteligente

Preste atenção na hierarquia de informações. Cada página da sua documentação deve ter relação com a anterior, de maneira que o dev consiga construir um raciocínio lógico com os documentos.
Caso você precise repetir alguma informação que já foi apresentada previamente, evite escrever tudo de volta. O ideal é fazer uma referência ao local onde o cliente pode encontrar a resposta que procura. Dessa maneira, seu documento fica mais organizado e sucinto.
Por fim, lembre-se de usar palavras-chaves que possam ser buscadas com facilidade. Isso, juntamente com títulos bem escritos e destacados, vai facilitar a leitura do material.

Compartilhe a documentação com o seu time

Antes de lançar a documentação da sua API para os consumidores, conte com o apoio do seu time. Peça para que desenvolvedores que não participaram diretamente do projeto — e que, portanto, não têm tanta familiaridade com a solução — vejam se o passo a passo está claro.
O ideal é que eles avaliem detalhes como parâmetros obsoletos, endpoints que não ficaram claros ou descrições muito vagas. Você também pode convidar os usuários a sugerirem melhorias na sua documentação!

Escreva exemplos detalhados

Você quer evitar uma enxurrada de mensagens no seu suporte? Então seja detalhista. O seu time já está com a mão na massa e entende bem o uso da API. Então que tal oferecer códigos que podem ser simplesmente copiados e colados pelo consumidor?!
Além disso, é interessante trazer exemplos de como a solução pode ser aplicada. Além de facilitar a integração, esse cuidado garante que o desenvolvedor curioso — que está apenas lendo a sua documentação antes de adotar a API em si — entenda ainda melhor como será o uso.
Traga exemplos detalhados quando a sua API apresentar diversos endpoints e soluções complexas. Os consumidores e o seu time de suporte agradecem!

Lembre-se de que você não precisa documentar tudo

Seja detalhista, mas nem tanto. Pode ser que a sua API seja fantástica. Porém, o objetivo do cliente é apenas realizar essa integração, não entender a fundo todos os detalhes a respeito da sua solução. Analise com cuidado o que realmente é importante para o consumidor, trazendo exemplos básicos e que podem ser incorporados com facilidade.

Títulos efetivos

Ter o apoio da sua documentação é fundamental, mas vamos combinar que o cliente não vai querer passar horas lendo os seus docs. Portanto, o interessante é caprichar nos títulos. Dessa maneira, os desenvolvedores conseguem encontrar o que procuram com mais facilidade.

Autenticação

Diversas API contam com esquemas de autenticação antes que o consumidor consiga começar a adotá-las. Veja se essa fase está documentada corretamente. Além de facilitar a vida do cliente, contar com documentos bem feitos desde essa fase passa uma boa impressão para quem está te contratando.

Mensagens de erro claras

Eventualmente o seu consumidor vai cometer algum erro durante a integração. Nestes momentos, é fundamental que ele se depare com mensagens de erro que sejam esclarecedoras. Em vez de simplesmente dizer que algo não está certo, apresente possíveis soluções de como superar o problema.

Evite jargões

Ter em mente qual é exatamente o público que vai entrar em contato com a sua documentação é importante para saber qual linguagem deve ser usada nos seus manuais. Um erro comum cometido nesse tipo de material é supor que todas as pessoas que vão entrar em contato com ele  têm domínio sob os sistemas de API.
Evite jargões muito técnicos, ou então procure explicá-los quando tiver que adicionar algum deles na documentação. Se você tiver dúvida se os seus materiais estão em um português claro, mostre o material para clientes ou pessoas que não estão envolvidas no projeto. É melhor ser intuitivo e claro do que perder um cliente ou contar com uma série de mensagens no seu suporte.

Pense na documentação enquanto ainda está desenvolvendo

Crie o hábito de já pensar na documentação enquanto está criando os códigos. Ao ter esse costume, você pode alterar alguns detalhes no código da própria API, por perceber que a explicação dela não ficará clara para os consumidores.

Leia também:
Qual é o ciclo de vida de uma API?
API model canvas: o que é e como utilizar?

Ferramentas para fazer uma boa documentação:

Para criar uma boa documentação você pode contar com o auxílio de algumas ferramentas. Separamos duas, que são bem famosas no mercado:

1- Swagger

A Swagger é uma das ferramentas para documentação mais antigas do mercado. Com ela, os seus docs podem ser gerados automaticamentes, a partir das anotações do código. Você também pode escrever manualmente os arquivos JSON, publicando-os no seu próprio servidor.

2- API Blueprint

A API Blueprint é uma especificação baseada em Markdown, o que permite que a edição dos materiais até mesmo por quem não tem familiaridade com códigos. Grande parte das suas ferramentas são open source e o seu objetivo é ser acessível, garantindo colaboração e fácil prototipação.

Conclusão:

Fazer uma boa documentação dá trabalho. Além disso, ela também envolve mais pessoas do que simplesmente quem criou os códigos da API. Clientes e outros membros do time podem ser acionados para garantir que todos os materiais fiquem claros.
Apesar de todo esse trabalho, ela é a fundação e às vezes o primeiro contato que os consumidores terão com a sua solução. Garantir que essa primeira impressão seja positiva e acessível é o início de um bom relacionamento com o consumidor.
Invista tempo na sua documentação e atualize esses materiais sempre que uma nova funcionalidade surgir. Os seus clientes agradecem!