Usando um protótipo como uma especificação de produto de API

Como Gerente de Produto de Experiência do Desenvolvedor no SendGrid, tenho a tarefa de identificar oportunidades, recursos e produtos que envolvem nossa API. Uma coisa em que tenho trabalhado é identificar métodos para tornar mais eficaz a comunicação de minhas ideias de produtos para outros PMs, engenheiros e clientes.

Aprendi que um Documento de Requisitos de Produto (PRD) monolítico é uma maneira menos que ideal de fazer isso e que uma interface testável incluindo as mesmas informações de uma especificação de produto seria uma alternativa poderosa. O problema com os PRDs é que eles geralmente são muito grandes e principalmente texto. É muito fácil perder o seu lugar ou perder algo realmente importante.

Nossos amigos em UX resolveram esse problema com ferramentas como o Invision , onde eles fornecem uma interface clicável que você pode tocar e usar, em vez de um documento ou wireframe que simplesmente descreve a interface. Como uma API é uma interface, precisamos de uma ferramenta que permita a interação com a especificação em tempo real, em vez de um monte de texto descritivo e JSON em um documento.

Definição de Requisitos

Como deve ser essa interface testável como especificação de produto? Como funcionaria? Isto existe?

Enquanto lia o Capítulo 18, “Reinventando as especificações do produto”, de Marty Cagan's Inspired: How to Build Products Customers Love , percebi que queria compartilhar uma ferramenta que tenho usado que satisfaça os requisitos de Cagan para uma especificação de produto, a maior parte do sua lista de desejos para especificações de produtos e minha própria lista pessoal de requisitos de protótipo como especificação.

Requisitos de Cagan*:

• A especificação deve descrever a experiência completa do usuário.
• A especificação deve representar com precisão o comportamento do software.
• Você deve ser capaz de comunicar o produto de forma que todas as partes interessadas obtenham o que precisam.
• A especificação vai mudar
• É preciso haver uma única representação mestre da especificação para reduzir a ambiguidade e a versão.

Lista de desejos de Cagan*:

• Você precisará complementar o protótipo [com]:
  • Logíca de negócios
  • Requisitos de lançamento
  • Requisitos de entrega da plataforma
  • Casos de uso
• Eu realmente quero ser capaz de anotar o protótipo

Meus requisitos para protótipo como especificação:

• O protótipo deve ser a especificação.
• A documentação deve ser integrada ao protótipo.
• Todos na empresa que precisarem devem ter acesso ao protótipo e à documentação.
• O cliente deve poder acessar a parte funcional do protótipo para teste do usuário.
• O protótipo deve substituir a especificação e funcionar o mais próximo possível da funcionalidade pretendida sem conectar um produto acabado.
• Deve ser fácil fazer e registrar alterações no protótipo.
• Deve ser fácil fazer variações A/B que possam ser testadas por qualquer pessoa com acesso ao protótipo.
• Deve ser fácil exportar a documentação do cliente do protótipo.

Apresentando o StopLight

A ferramenta que tenho usado e que satisfaz quase tudo acima é chamada Stoplight.io . É em sua essência um mecanismo de documentação de API e proxy da web. Ele permite que você defina sua API usando uma interface de usuário intuitiva, que tem o melhor do Swagger e do RAML nos bastidores como seu mecanismo de especificação, além da capacidade de importar ou exportar de qualquer formato.

Como o StopLight é uma ferramenta de documentação, você pode definir as solicitações, respostas, cabeçalhos e descrições para seus endpoints. Com o recurso de proxy, você pode chamar sua API e verificar se suas chamadas correspondem à sua especificação ou descobrir automaticamente seus endpoints para obter a maior parte de sua documentação escrita automaticamente.

O proxy do StopLight também possui vários outros recursos absolutamente incríveis:

• A capacidade de fazer chamadas simuladas para seus endpoints se seu produto não estiver concluído ou se você não quiser fazer proxy de suas solicitações.
• Servidor local para testar seu protótipo em sua máquina.
• Servidor remoto para testar seu protótipo na Internet.
• Middleware, escrito em Javascript, para definir o código que pode ser executado antes e/ou depois que os endpoints do seu protótipo forem chamados.

Se você comparar a combinação da minha lista de desejos, os requisitos de especificação de Cagan e sua lista de desejos com a funcionalidade que o StopLight fornece, poderá ver que o StopLight satisfaz todas as necessidades e desejos:

• Documentação apenas interna do protótipo e seus recursos.
• Um protótipo completo da funcionalidade facilmente acessível.
• Uma interface testável que tem a capacidade de alternar recursos variáveis ​​para teste e feedback do usuário.
• Uma maneira fácil de criar uma versão do seu protótipo para uma conversa específica, para que você possa modificar a funcionalidade do protótipo quase em tempo real para ilustrar e verificar o feedback recebido.

O fluxo de trabalho no StopLight é simples e pode ser feito por qualquer pessoa , independentemente de sua capacidade técnica:

• Crie um novo projeto.
• Adicione a especificação clicando e digitando informações sobre o terminal, seus parâmetros, solicitação e resposta.
• Adicione as informações de especificação sobre seu protótipo na tela Definição.
• Se você tiver recursos opcionais, adicione-os usando o middleware.
• Ative a zombaria.
• Copie/cole a URL pública do servidor simulado e compartilhe-a para obter feedback.

Se você estiver visitando um cliente e quiser experimentar o protótipo em tempo real, basta baixar a definição para seu computador, criar um novo projeto com o nome de sua visita e importar a definição. Agora você pode alterar o que quiser sem alterar seu protótipo original. Quando você está de volta e mesclando ideias, é tão fácil fazer alterações quanto construir o protótipo em primeiro lugar.

Como gerente de produto da experiência do desenvolvedor, o StopLight não está apenas me ajudando a fazer meu trabalho com mais eficiência, é muito simples de usar e facilita as etapas de preparação de entrega para documentar a API, pois a documentação foi iniciada antes das etapas de validação do cliente e é atualizada durante todo o processo. Existem muitos outros casos de uso e recursos que o StopLight fornece, mas esse pode ser o que impactou mais significativamente meu trabalho.

*Os requisitos e a lista de desejos de Cagan são citações diretas de Inspired: How to Build Products Customers Love.