Por Bruno Pedro 

Enquanto quase todo mundo parece concordar que documentação é de extrema importância ao lançarmos uma API, pouco é dito sobre como isso pode realmente afetar a adoção de APIs. Jeffrey Hammond, Principal Analyst do Forrester, afirma que “padrões de adoção estão mudando em direção aos desenvolvedores”, dando-lhes o poder de “bloquear ou adicionar a adoção de software”. Isso quer dizer que uma forma significante de persuadir tomadores de decisão a escolherem seu software ao invés do de seu concorrente é ganhando a confiança e a segurança de desenvolvedores.

Uma das melhores formas de aumentar a consciência e interesse em seu produto é tornar sua API imediatamente utilizável pelo desenvolvedor. E isso começa pela documentação.

Como a documentação da API afeta sua adoção?

 Documentação toma um papel central na forma como a API é percebida pelos desenvolvedores. Uma documentação pobre é frequentemente sinal de uma API com má manutenção – o que os desenvolvedores irão tentar evitar a todo custo. Quanto mais você focar na documentação de sua API pensando no uso de desenvolvedores, maior será a confiança ganha e melhor será a experiência para eles.

Experiência de integração

Comece pela primeira impressão. O desenvolvedor não deve levar mais de cinco minutos para compreender sua API e começar a usá-la. A única forma de tornar isso realidade é fornecendo uma experiência de integração simplificada e concisa. Documentação deve levar o desenvolvedor rapidamente ao estágio em que já está usando a API com pouco ou nenhum esforço.

Uma forma possível de fazer isso acontecer é criando um ambiente sandbox no qual desenvolvedores podem brincar com a API sem afetar seus servidores de produção. Isso permite que você ofereça um processo mínimo de assinatura, perguntando apenas o que é realmente necessário ao invés de ter um processo de registro extenso que pode afastar muitos desenvolvedores.

Boa documentação deve informar claramente aos desenvolvedores o que eles precisam fazer para começar – e como fazer isso. Se sua API funciona com tokens, gere um on-the-fly e deixe os desenvolvedores o utilizarem imediatamente. Se você usa OAuth, forneça uma informação de consumidor falso e até mesmo um acesso token para que desenvolvedores possam começar fazendo chamadas na API imediatamente.

Lembre-se de que esse é apenas o primeiro passo para engajamento e desenvolvedores ainda estão avaliando sua API. Você deve deixar eles experimentarem o máximo possível, mas sem comprometer seus sistemas de produção ou qualquer informação de usuário real.

O poder da experimentação

Para deixar desenvolvedores experimentarem com sua API, você pode seguir qualquer combinação das seguintes estratégias:

1. Ofereça um console de API: Isso é o mínimo que você deve oferecer como uma ferramenta de experimentação. Com o console de API, desenvolvedores são encorajados a testar imediatamente o que eles veem na documentação e enxergar chamadas reais de APIs tomando forma.
2. Ofereça um SDK: Publique um SDK open source na maior quantidade possível de linguagens de programação que seus desenvolvedores alvo usam. Forneça documentação SDK compreensiva e a faça de fácil instalação e configuração. Formas populares de distribuição de SDKS incluem npm para Node.js, Packagist para PHP, RubyGems para Ruby e PyPI para Python.
3. Publique tutoriais: Comece com um guia de começo rápido seguido tutoriais mostrando como implementar casos interessantes de uso com sua API. Forneça trechos de exemplo usando SDKs na maior quantidade de linguagens diferente possível para que desenvolvedores possam simplesmente copiar e colar e comunicar-se com sua API com o mínimo esforço possível.

Ao seguir essa abordagem você oferecerá uma documentação rica e compreensiva com todas as ferramentas que um desenvolvedor precisa para começar a utilizar imediatamente a API. Desenvolvedores serão capazes de escolher suas linguagens favoritas de programação e seguir seus tutoriais sobre como implementar casos específicos que estejam procurando.

Construir isso tudo do zero não é tarefa fácil. Documentação é algo que requer muito foco em detalhes e deve refletir continuamente as últimas mudanças na API. Nosso conselho é sempre seguir os padrões da indústria e usar métodos e ferramentas já provadas.

Ferramentas que o ajudam a construir ótima documentação

Dentre todas as ferramentas relacionadas a APIs, documentação é provavelmente a área que mostra maior crescimento. Isso é particularmente interessante por conta de a documentação ser tradicionalmente algo que desenvolvedores são pouca atenção quando lançar o código. Existem agora diversos padrões e ferramentas que reduzir drasticamente o tempo de implementação de documentação.

Swagger, por exemplo, é uma cadeia de ferramentas open source que permite fácil criação de documentação interativa. Apigee está usando Swagger em seu kit de ferramentas Apigee-127, que é um conjunto de ferramentas de primeira para construção de APIs ricas e a nível empresarial que são executadas em qualquer provedor PaaS que suporte Node.js. Para usar o kit de ferramentas, basta começar modelando sua API com um editor Swagger built-in e a partir deste ponto, o código da API é gerado automaticamente.

Apigee-127 é um conjunto de ferramentas de modelo de primeira para a construção de APIs ricas e de classe empresarial que são executados em qualquer provedor de PaaS que suporta Node.js

RAML, ou RESTful API Modeling Language, é a uma especificação e conjunto de ferramentas que permite modelar a API e a fornecer documentação a partir disso. Isso tem ganhado bastante adoção no espaço empresarial, provavelmente porque segue três principais princípios: é humanamente legível, simples e pode ser dividido por padrões.

Com uma abordagem ainda mais humana, API Blueprint o deixa escrever as especificações de sua API em Markdown e serve como sua documentação. O mesmo arquivo Markdown também é usado por uma ampla gama de ferramentas para gerar código, correr testes de integração e depuração da API. O número de formas que API Blueprint pode ser manipulada é impressionante já que há mais de 15 ferramentas que podem convertê-la em outros formatos.

Read the doc é um serviço de documentação hospedada que o permite escrever a documentação sem se preocupar em hospedá-la você mesmo ou em manter suas mudanças. Sem preocupação para esses detalhes, você pode simplesmente focar na qualidade de sua documentação. No fim é isso o que mais importa. Além disso, uma feature interessante é seu suporte webhook, que permite conectar facilmente seu sistema de controle de versão (GitHub, por exemplo) e iniciar a atualização da documentação automaticamente conforme você faça uma.

Conclusão

Já que documentação é cada vez mais o principal canal de adoção de APIs indicando o caminho para desenvolvedores a entenderem e apreciarem, ela deveria ser o principal tópico em sua agenda. De acordo com inúmeras autoridades no campo das APIs, desenvolvedores estão tomando o papel principal no processo de tomada de decisão ao considerar um novo produto ou serviço.

Documentação é o rosto de sua API e é a primeira coisa que desenvolvedores veem quando entram em seu web site. Você deve tornar sua experiência o mais suave possível e oferecer um processo de engajamento que possa começar com um rápido onboarding e leva-los a experimentar sua API ao implementar seus casos de uso preferidos. Você deve considerar oferecer SDKs em linguagens populares e uma ampla gama de tutoriais e guias para tornar a jornada de implementação tranquila.

Por fim, se a opinião dos desenvolvedores sobre sua API é positiva, eles irão recomendar o seu produto ao invés do da concorrência. Como resultado você ganha novos consumidores!

Sobre autor

Bruno Pedro tem mais de quinze anos em experiência como desenvolvedor em startups e grandes empresas. Também é editor no API UX, site colaborativo voltado para experiência de usuário em APIs. 

Traduzido de Nordic APIs