O que é uma boa documentação
Se você está chegando agora na área saiba que é responsabilidade do desenvolvedor também documentar suas alterações. Se você está na área a tempos, deveria já estar documentando, né? Como redator técnico com meses de experiência, eu criei um conjunto de arquivos markdown que representam uma estrutura para documentação de API. Esse exemplo básico pode ser usado em qualquer projeto e pode ser encontrado em sample-api-documentation.
Este projeto foi criado com base em minha experiência trabalhando com diferentes APIs e minhas observações sobre os desafios comuns que desenvolvedores e redatores técnicos enfrentam ao documentá-los.
O projeto sample-api-documentation destina-se a ser usado como ponto de partida para documentar suas próprias APIs ou como referência para as melhores práticas em documentação de API.
Uma boa documentação
Dentro do projeto há três tipos de documentação extremamente importante: guides, reference e changelog.
Ok, agora vou me contradizer com o que disse alí em cima… se você não consegue criar a documentação dos três tipos, escolha uma para ser o seu formato de documentação. O ideal é os três, mas tendo ao menos uma bem feita já ajuda bastante.
Guides
A sessão do guia (ou guides) é responsável por mostrar toda a questão de negócio envolvida. No exemplo documentado no projeto, não é só criar um consumidor para tê-lo disponível, é preciso criar também uma conta bancária e associá-la ao consumidor.
Ter apenas as informações de cada endpoint não faz com que o desenvolvedor, a pessoa responsável pela usabilidade, o gerente de produto e outros envolvidos no desenvolvimento do software sejam capazes de entender o que é preciso ser feito.
Na antiga empresa, tínhamos o lema de que o guia deveria ser entendido por qualquer pessoa, técnica ou não. O departamento comercial da empresa usava e elogiava que fizemos pensando nisso, pois facilitava muito o trabalho deles.
Reference
O reference é a parte mais técnica; ele inclui seções para definir endpoints, formatos de solicitação e resposta, e detalhes de autenticação.
A seção de endpoint fornece uma descrição clara e concisa de cada endpoint, incluindo o método HTTP, URL e um breve resumo do propósito do endpoint. As seções de solicitação e resposta descrevem o formato esperado e os tipos de dados para cada solicitação, e a resposta retornada pela API. A seção de autenticação fornece detalhes sobre os métodos de autenticação necessários para acessar a API.
Também acho válido uma sessão de pré-requisitos, pois nem sempre é só chegar usando a API; você precisa de alguns pontos antes, que deveriam estar especificados no guia. Porém, o desenvolvedor, a gente conhece, ele vai tentar ler o mínimo possível, portanto é preciso facilitar o acesso à informação. Assim, mesmo tendo descrito no guia, caso ele use somente o reference, ele vai conseguir obter um resultado válido (com mais dor de cabeça, sim? mas quem mandou não ler a documentação).
Changelog
Também chamado de novidades da versão, ou release notes, aqui sempre que você cria, altera ou remove uma funcionalidade, você apresenta-a ao desenvolvedor, mostrando o que mudou.
Em poucas palavras, você consegue ensinar uma nova funcionalidade para quem já está acostumado com sua API, sem que ela precise ler toda a documentação (tipo git, né? que só salva o que foi mudado).
No final, você educa a pessoa a usar a API da maneira que você e sua empresa pretendem, mostra mais recursos do sistema, gera conteúdo e se torna o queridinho do marketing da empresa, pois agrega um valor muito grande.
Porém, tecnicamente, é importante saber para onde está indo. Visualizar os changelogs permite que os desenvolvedores envolvidos e consumidores da API entendam quais pontos estão sendo focados pela empresa, o que está nos planos e nas prioridades dos desenvolvedores. Ao ver, por exemplo, que todos os esforços recentes estão em eventos sendo disparados por webhooks, ele vai perceber que não é para usar aquela API que lista os eventos que foram disparados e que não recebe atualização há anos.
Mas tão importante quanto tudo que foi descrito aqui é listar quais problemas foram resolvidos e se existe algum conhecido. Claro, não é ideal ter problemas conhecidos na sua API (use o crédito que você ganhou com o marketing ali em cima), mas é extremamente importante ser transparente com o desenvolvedor, caso contrário o SAC vai receber várias ligações.
"Ah, mas se está na main, não é para ter problema." Concordo, mas nem sempre é verdade. Então, se estão implicando muito com isso, liste somente para as APIs que estão em beta.
Espero que este projeto ajude você a documentar melhor suas APIs, entenda o trabalho que é ter tudo direitinho e que o trampo de um Tech Writer é extremamente valioso, porém isso não exclui a necessidade de você documentar.