Context
Implementation of Building Blocks (reusable microservices) as part of the software architecture transformation at one of Brazil’s largest private banks.
Problem
The software architecture transformations at the client highlighted the need for APIs documentations for these new microservices and the selection of an appropriate tool for internal implementation.
Contribution
- Refinement of OpenAPI Specifications using swagger editor, seeking standardization of API contracts, following best practices, as well as other standards established by the client’s API governance area;
- Rewriting and elaboration of descriptions for API attributes and endpoints, ensuring an accessible language with the use of technical writing tools such as active voice, elimination of anthropomorphism, and correct term selection;
- Meetups with squad members to ensure the implementation of good documentation practices.
Impact
- Greater satisfaction of API consumers, facilitating the integration, understanding, and adoption of the new Building Blocks;
- The gradual reduction in support calls to clarify doubts with the engineers.
Contexto
Implementação de Bulding Blocks (microserviços com características reaproveitáveis), na transformação da arquitetura de software do cliente, um dos maiores bancos privados do Brasil.
Problema
As transformações na arquitetura de software do cliente evidenciaram a necessidade da elaboração de documentações para as APIs destes novos microserviços e a escolha de uma ferramenta adequada para implementação interna.
Contribuição
- Refinamento das OpenAPI Specifications com o swagger editor, buscando a padronização dos contratos das APIs, seguindo boas práticas, também outros padrões estabelecidos pelo setor de governança de APIs do cliente;
- Reescrita e elaboração de descrições para atributos e enpoints das APIs, garantindo uma linguagem acessível com o uso de ferramentas de redação técnica como voz ativa, eliminação de prosopopéias e escolha correta de termos.
- Meetups com as squads responsáveis visando garantir a implementação de boas práticas de documentação.
Impacto
- Maior satisfação dos consumidores das APIs, facilitando a integração, entendimento e adoção dos novos Building Blocks;
- Diminuição gradativa de chamadas para suporte e esclarecimento de duvidas com os engenheiros.