Tempo de leitura: 9 minutos
APIs fazem o mundo girar. Os desenvolvedores usam APIs quase todos os dias – por algumas estimativas, eles passam mais de 10 horas por semana trabalhando com APIs. Isto cobre não apenas o uso delas, mas também a pesquisa, o googling para suporte, o estudo de revisões e, claro, o rummaging em torno da documentação. O quão claro, fácil, útil e suportado é o seu API determina toda a experiência do desenvolvedor (DX) – uma resposta emocional que os dispositivos têm para o produto. Na economia da API, uma grande experiência do desenvolvedor é fundamental. As APIs que ajudam os desenvolvedores a ter sucesso e são uma alegria de usar terão toneladas de usuários e se elevarão acima da concorrência. E começa no momento exato em que eles abrem a documentação pela primeira vez.
Veja este vídeo para uma inrodução à tecnologia da API
Hoje vamos falar sobre como promover uma experiência positiva do desenvolvedor na documentação da API. Mas primeiro, precisamos entender o que faz com que os documentos da API sejam ruins.
O que os desenvolvedores odeiam na documentação da API
A comunidade dev é uma comunidade apaixonada. É especificamente apaixonada pelas coisas de que eles não gostam. Se eles não gostam de uma API, é na maioria das vezes por causa de documentos junky, mesmo que o produto seja realmente ótimo. Aqui estão alguns problemas comuns que os devs têm com API docs.
Não é escrito usando linguagem humana simples. Este é um problema comum para docs gerados automaticamente ou docs que são negligenciados pelos criadores. Embora muitas ferramentas de geração de documentação estejam fazendo um ótimo trabalho comentando o código, elas não podem substituir explicações reais em inglês escritas por um desenvolvedor ou escritor técnico.
Tem muito poucas amostras de código. Este é outro extremo do espectro onde as explicações são abundantes, mas há exemplos mínimos do código real.
Está disponível apenas para usuários registrados. Esta manobra não tão simples não faz nada pelo seu marketing. Ela apenas frustra as pessoas que querem saber o que sua API faz antes de decidir se a querem (como qualquer pessoa sadia faria).
É muito longa/ não pode ser encontrada/inacurada/ não foi atualizada em anos, etc. Criar bons documentos é quase tão importante quanto construir uma boa API. Porque os documentos mal escritos ou aqueles que não podem ser encontrados simplesmente procurando no Google “Product API” estão falhando em todo o esforço de desenvolvimento. Se você estiver interessado, nós já delineamos documentos específicos de documentação técnica em geral. Mas os documentos da API merecem um artigo dedicado. Então como você escreve grandes documentos da API?
Adopt desenvolvimento orientado a especificações
Desenvolvimento orientado a especificações (SDD) é similar ao desenvolvimento orientado a testes no qual você escreve casos de teste para cada recurso e então escreve código que deve passar neles. No SDD, você cria documentos ou pelo menos algumas partes deles em paralelo com a construção de uma API, geralmente seguindo um certo formato de descrição da API chamado especificação.
Uma especificação da API é como um modelo dos seus futuros documentos, a linguagem unificada que descreve o design da sua API, explica como ela funciona e o que esperar dela. Existem algumas especificações, tais como RAML (RESTful API Modeling Language), OpenAPI (anteriormente Swagger), e API Blueprint, mas há uma tendência em curso para combinar todas as especificações sob a capa do OpenAPI.
Estas especificações têm ferramentas de documentação pré-construídas que permitem escrever e gerenciar seus documentos. Por exemplo, a API Console gera automaticamente documentos a partir de formatos RAML e OpenAPI e o ajuda a executá-los em sua aplicação web existente ou como uma aplicação autônoma.
API Console permite que você construa um portal web para seus documentos API a partir de especificações RAML e OpenAPI
Source: Pawel Psztyc
Alternativo às soluções tradicionais de documentos API como WordPress ou CMSs Drupal, os produtos de especificação da API são de código aberto, criados pela comunidade dev para a comunidade dev, têm analisadores em diferentes linguagens de programação e suporte constante a criadores.
Escrever para o nível de entrada
Existe uma razão pela qual a documentação técnica normalmente não é escrita pelos próprios desenvolvedores – é o trabalho de escritores técnicos, especialistas em traduzir aspectos técnicos para um formato legível. Mas mesmo escritores técnicos tendem a vazar um pouco de jargão para o texto.
Uma API como qualquer produto de software é criado para um público específico. Mas o público para documentação é vasto. Há três grupos principais de usuários de documentação:
- developers que irão interagir intimamente com os documentos
- decision-makers como CTOs e arquitetos de soluções que querem determinar se a sua API será um bom ajuste rapidamente
- observadores como jornalistas, escritores técnicos, e até mesmo concorrentes que não necessariamente usarão a sua API nunca.
E mesmo dentro de cada um desses grupos, há pessoas de diferentes habilidades, papéis e necessidades, e todos eles devem ter uma experiência positiva com os documentos. Como você visa todos eles? Visando os usuários menos experientes. Então, como você escreve documentos para um recém-chegado?
Comece com as oportunidades e não com os aspectos técnicos. Cumprimente os usuários com uma história convincente contando como sua API pode enriquecer seu produto ou tornar a vida dos desenvolvedores dez vezes mais fácil.
>
Amazon Alexa API docs começam explicando o que o Alexa faz e que benefícios ele pode trazer para o cliente
Mostrar por onde começar. Os docs APIs são notórios por serem demasiado esmagadores e assumindo que os utilizadores têm uma vasta experiência com APIs. A seção de início é obrigatória, e deve ser escrita com paciência para um usuário potencial.
Facebook fornece uma referência clara para iniciantes e segue o processo de início passo a passo
Criar instruções para os casos de uso mais comuns. Você provavelmente já sabe para que funções as pessoas usam sua API. Crie seções separadas endereçando-as e inclua exemplos de mensagens lá.
Use um tom de conversação. A comunidade de desenvolvedores é descontraída e informal, então eles não vão apreciar a linguagem corporativa seca, mesmo que soe mais “profissional”. Bons documentos sempre falam com humanos.
Eduque em ferramentas externas. Se a sua API requer o uso e compreensão de produtos e conceitos de terceiros como OAuth ou npm, inclua links para docs ou guias de instalação.
Faça com que seja fácil de aprender. Os documentos API não são instruções de montagem da IKEA; eles são a fonte de aprendizagem. Enriqueça sua documentação com FAQs, tutoriais, blogs e até mesmo vídeos quando possível.
Secções obrigatórias corporativas
Em 2019, o SmartBear, o desenvolvedor da Swagger, pesquisou desenvolvedores e usuários de API. Eles descobriram quais recursos da docs são considerados os mais importantes na comunidade, dando-nos uma lista das seções de documentação obrigatória que os desenvolvedores e usuários querem cobrir. Nós vamos passar por algumas delas.
SmartBear pesquisou 3.000 praticantes de API
Exemplos. Exemplos são geralmente apresentados como peças de código, que são úteis o suficiente, mas podem ser tornados ainda mais práticos. Por exemplo, incluindo uma transcrição de campos como é feito em documentos Médios ou mesmo criando uma API falsa para os desenvolvedores testarem e usarem fazendo chamadas reais. APIs simuladas podem ser facilmente compartilhadas através de uma URL ou no GitHub, e se feitas com um certo nível de detalhe, até mesmo usadas no produto final.
Status e erros. Existem códigos de status padrão e aqueles específicos para as suas APIs. É uma boa idéia incluir todos os erros que podem ser acionados pela sua API. Erros são frequentemente colocados em uma página dedicada dos documentos, mas faz sentido duplicar alguns deles diretamente sob o ponto final onde eles mais aparecem.
Autenticação. A maioria dos documentos da API começam com autenticação e autorização. Ele deve cobrir informações sobre como obter uma chave API e como autenticar requisições, incluindo possíveis erros, tempos de expiração do token e uma explicação sobre a sensibilidade da autenticação (basicamente lembrando que as chaves não podem ser compartilhadas, e onde elas podem ser usadas).
RequisiçõesHTTP. O fornecimento de solicitações web em HTTP é o mínimo necessário para documentação. É normalmente assumido que o devs saberá como enviar requisições HTTP em seu idioma de escolha, mas às vezes, os criadores de APIs incluem requisições em vários idiomas. Isso pode ser feito automaticamente via ferramentas de especificação da API e ferramentas de gerenciamento de API como Postman.
Utilizar layout padrão da indústria
Se você estiver usando um gerador de documentação, o layout já está decidido para você. A maioria dos documentos API parecem e sentem o mesmo. Se você já usou alguns, você sabe como abordar novos documentos. Ainda assim, organizar grandes volumes de dados, tornando-o encontrado e fácil de navegar, é uma tarefa complexa. Aqui estão algumas características do layout mais funcional.
Dynamic layout. Você pode reconhecer uma API desatualizada através de sua documentação estática. Uma única página ou mesmo um documento PDF não a corta em 2020. Os documentos dinâmicos são fáceis de ver, atualizar e marcar.
Conteúdo pegajoso. Não, a barra de navegação não distrai nem rouba espaço precioso na tela. Mantenha sempre o conteúdo à vista.
Tres colunas de layout. Não usado com muita frequência, este layout permite que você tenha outra coluna à direita para os exemplos de código. Claro, isto só faz sentido se tiver uma tonelada de texto e quiser realçar o código para que os utilizadores não tenham de percorrer para a frente e para trás ou alternar entre separadores.
>>656565>>
Documentos API do HubSpot usam um layout de três colunas
Utilizar cores de contraste para a sintaxe. Os desenvolvedores gastam muito tempo olhando para os seus exemplos de código, então torne-os legíveis e separe diferentes componentes por cor.
>
>
>
Este exemplo dos documentos Graph API do Facebook também mostra como você pode usar diferentes abas para escolher entre SDKs
Salvado estado de rolagem. Este é um pequeno detalhe que qualquer desenvolvedor irá apreciar. Você também pode usar links de âncora para especificar diferentes seções da página caso elas copiem a URL.
Encorajar o feedback. Seus documentos são sua principal ferramenta de marketing – se as pessoas os adorarem, eles usarão sua API sobre a da concorrência e conduzirão a comunidade em torno dela. A mensagem habitual “Esta página foi útil?” lhe informará o quão bem você está endereçando as perguntas dos devs e o formulário de feedback será usado com frequência desde que você o entregue.
Não abandone seus docs
Os docs desatualizados são os maiores peeve dos usuários de API. Este também é um dos erros mais comuns. Desenvolvedores geralmente escrevem sobre atualizações vários dias depois de lançá-las, às vezes limitando-se a algumas frases. Isto acontece porque não há um processo estabelecido para atualizações de docs e não é responsabilidade de ninguém. Veja como assegurar atualizações regulares e úteis de documentos.
Preparar documentos antes das atualizações. Faça disso um passo adicional em seu plano de lançamento, não os execute antes de ter parágrafos bem escritos, detalhados e editados para introduzir suas atualizações.
Retirar dados depreciados regularmente. Os documentos têm de ser revistos frequentemente, pelo menos uma vez a cada poucos meses. Os recursos de feedback do usuário permitirão que você capture inconsistências mais cedo e deve sempre haver um membro da equipe responsável por revisá-los e reagir às atualizações.
Utilizar a análise para melhorar os documentos. A análise da API padrão lhe dirá quais pontos finais são usados com mais frequência, para que você possa se concentrar em certas partes da documentação e fornecer informações mais úteis ou criar tutoriais dedicados. Monitore os casos de uso das suas APIs porque isso lhe permitirá ampliar a proposta de valor e atualizar os documentos com mais possibilidades.
Great API documentation examples
Há toneladas de bons documentos para explorar e aprender com eles. Além dos exemplos que compartilhamos ao longo do artigo, aqui estão mais alguns para você apreciar e tomar nota.
Documentação da API média
Documentos da API média não necessariamente obedecem a todas as regras que listamos hoje, mas são ótimos para a funcionalidade limitada que esta API suporta – postar e pesquisar publicações em Médio. Eles são compartilhados no GitHub, têm um conteúdo realmente curto mas claro com toneladas de exemplos, cada um terminando com uma transcrição de todos os parâmetros mencionados no código, incluindo possíveis erros. É notavelmente simples, mas confiável – todas as sugestões podem ser feitas diretamente no GitHub e os documentos são atualizados regularmente.
>
Mailchimp API documentation
Mailchimp percebe que a maioria de seu público são profissionais de marketing e usa uma linguagem que permite até mesmo pessoas sem tecnologia entenderem como trabalhar com suas APIs. Num relance, cada seção segue a mesma estrutura:
- o que um endpoint faz e o que o guia permitirá aos usuários fazerem
- o que você precisará – quaisquer acessos ou contas que um usuário deve obter primeiro
- o que cada função tem com uma descrição de texto, um exemplo de código em várias línguas, e às vezes screenshots da interface.
Existe até um botão de cópia para cada código – um detalhe que as não-tecnologias certamente apreciarão.
Twilio API documentation
Twilio tem documentos API muito bons. Embora os docs sejam apenas a ponta do iceberg de toda a ajuda que o Twilio compartilha – existem SDKs em vários idiomas e aplicativos de amostra para iOS, Android, e web. Primeiro de tudo, eles seguem a lógica de três colunas com o código diretamente à direita do guia. As ações mais simples são explicadas com detalhes e toneladas de links para informações adicionais e capturas de tela. O feedback também é encorajado através de um botão “Classifique esta página” e links para a equipe de suporte e a tag no StackOverflow.
Spotify API documentation
Embora os documentos da API web do Spotify sejam muito típicos, eles têm muitas informações adicionais em sua plataforma Spotify for Developers. Há demonstrações para funções básicas, aplicações simuladas, exemplos ao vivo construídos usando APIs e widgets Spotify, wrappers para diferentes linguagens de programação e, claro, o console. O console é basicamente uma documentação interativa onde você pode preencher seus dados (ou amostras) e explorar os pontos finais ao vivo. Produtos poderosos junto com uma forte base de conhecimento fazem do Spotify um parceiro confiável com quem os desenvolvedores gostam de trabalhar.
>
Trate os documentos com cuidado
Documentação é o único ponto de contato que você terá com a maioria do seu público, então você precisa aprender a se comunicar claramente através dele. A melhor dica aqui é fazer com que seja o trabalho de alguém. Muitas vezes, este é um escritor técnico que sabe falar com audiências de diferentes habilidades, que sabe traduzir as palavras dos desenvolvedores em pontos de ação, que monitora a manutenção e atualização oportuna dos documentos. Mas gerir uma grande documentação é possível mesmo sem um especialista na sua equipa. Ferramentas de gerenciamento de API como Swagger UI, Spotlight, Apiary e ferramentas de especificação de documentos têm uma ampla funcionalidade para ajudar você a fazer documentos que os desenvolvedores irão adorar.