É comum que a documentação de uma API seja frequentemente negligenciada por desenvolvedores, sendo considerada fator secundário.
Documentação de qualidade deveria ser vista como sendo tão parte do produto quanto a API em si, assim como vender bem algo envolve conhecer o seu público. Se esse público é um depurador maníaco, um gerente de produtos ou um novo e entusiasmado dev, documentação é a chave para uma adoção mais ampla. Com isso, é imperativo manter esses usuários atualizados e oferecer-lhes suporte.
A chave que determina onde possivelmente está um problema, qual a capacidade do produto ou que simplesmente atesta de forma clara processos fundamentais é a documentação. Independente do cenário, a falta de referência material pode afastar usuários em potencial. Felizmente, a tarefa de escrever a documentação não é mais manual desde que os frameworks de documentação de APIs automatizadas surgiram.
Produtos como Swagger, API Blueprint e RAML oferecem vários métodos para automaticamente criar documentação para todos os estágios do ciclo de vida de sua API. É mais fácil do que nunca disponibilizar a seus usuários suporte compreensível com as ferramentas práticas como essas.
Entretanto, criar documentação não é o suficiente. Manter esse trabalho atualizado é tão importante quanto uma vez que documentações pobres ou obsoletas frustram desenvolvedores – que podem decidir por tentar um provedor diferente. APIs mudam regularmente conforme bugs são resolvidos e novas funcionalidades são adicionadas, então tenha a certeza de comunicar mudanças para aqueles que dependem de seu produto. A ascensão da economia de APIs tem como pilar sua documentação, então garanta que ela foi construída em uma fundação sólida.
Por Martin W Brennan
Traduzido de ProgrammableWeb