Chegando à Station: A evolução da nossa plataforma de documentação de API

Há três anos, nossa plataforma de documentação foi lançada. Mal sabíamos o impacto que algumas das decisões de design que tomamos naquela época teriam hoje. Por exemplo, optamos por desenvolver um aplicativo web de código aberto usando Ruby on Rails, em vez de geradores de sites estáticos para arquivos Markdown, como o Jekyll, o Middleman etc.

A história até agora

Uma estrutura web, como o Rails, foi a escolha perfeita, pois ela não faz suposições sobre o que será desenvolvido com ela, o que lhe dá a flexibilidade de aceitar tudo.

Três anos atrás, não sabíamos qual seria, no fim das contas, o escopo do nosso projeto como uma empresa de APIs em rápida evolução. É difícil imaginar o quanto nossa plataforma de documentação cresceu, e é ainda mais difícil imaginar o que ela poderá se tornar no futuro.

Hoje em dia, as ferramentas relacionadas à plataforma aumentaram significativamente. Desde a verificação ortográfica automatizada e a internacionalização até as verificações de validade e estilo das especificações de API — e a lista não para de crescer.

Desde sua criação, a plataforma tem viabilizado o Vonage API Developer. O Vonage API Developer começou como Nexmo Developer e, nos anos desde sua criação, tornou-se parte da Vonage, líder global em comunicações unificadas na nuvem. Como resultado, as demandas e expectativas em relação à plataforma cresceram de forma aparentemente exponencial.

Essa não foi a conclusão da história da evolução da plataforma.

A história continua...

Seis meses atrás, outra equipe de produto da empresa entrou em contato conosco porque a ferramenta que eles usavam para o site de documentação havia chegado ao fim de sua vida útil. Eles estavam animados com a ideia de migrar para uma versão simples da plataforma Vonage API Developer, mas, infelizmente, ela ainda não estava pronta para uso. Não só o código da plataforma e a documentação do Vonage API Developer estavam no mesmo repositório, como também algumas das páginas e funcionalidades não haviam sido desenvolvidas para suportar outras modalidades de conteúdo específicas daquela linha de produtos.

A crescente complexidade das necessidades de ferramentas impostas a uma única aplicação Rails monolítica, aliada ao aumento do interesse na adoção da plataforma por diversas linhas de produtos da Vonage, nos levou a buscar uma alternativa melhor.

Foi por meio dessa pesquisa que chegamos à Station.

O que é o Station?

Nos últimos meses, separamos a parte de conteúdo do código da plataforma. Refatoramos o código para criar uma plataforma independente de conteúdo, capaz de suportar uma grande variedade de formatos de conteúdo e mídias, além de capacitar outras equipes em toda a empresa.

O Station é uma ferramenta de plataforma. Basta definir alguns arquivos de configuração e indicar o caminho para onde seu conteúdo está armazenado para que um site possa ser criado com um único comando no terminal.

Ele foi desenvolvido para oferecer os seguintes recursos prontos para uso:

• Uma solução para criar rapidamente sites com conteúdo baseado em texto

• A possibilidade de todos, independentemente do nível de conhecimento em programação, contribuírem com conteúdo de maneira simplificada

• Altamente personalizável para atender às necessidades de cada site por meio de um conjunto de arquivos de configuração

Em essência, o Station é um aplicativo Ruby on Rails (e Webpack) altamente personalizado, integrado a uma Ruby Gem — um pacote de software reutilizável na linguagem de programação Ruby. Para o desenvolvedor experiente em Rails, ele parecerá familiar. Para quem não está familiarizado com o Rails, não será necessário aprender as nuances do framework para executar ou contribuir com conteúdo para um site desenvolvido com o Station.

O que a Station faz?

Uma instalação do Station oferece, desde o início, a maioria dos recursos que você esperaria de um site de conteúdo: exibição de conteúdo rico em mídia e arquivos de especificação OpenAPI, tutoriais passo a passo, páginas da web criadas sob medida, casos de uso, possibilidade de enviar feedback, pesquisa de conteúdo e muito mais.

Não apenas o conteúdo, mas a maior parte do site pode ser personalizada por meio de arquivos de configuração. O trecho a seguir corresponde ao arquivo de configuração do cabeçalho e do rodapé do site.

É assim que eles são exibidos na página.

E agora?

Embora estejamos satisfeitos por termos criado uma plataforma robusta, capaz de dar suporte a qualquer site de conteúdo e que atualmente está sendo utilizada no site de documentação de duas de nossas equipes, ela ainda não está totalmente disponível para uso por todos.

Embora seja de código aberto, a gem está sendo lançada por meio do registro de pacotes do GitHub, e as versões ainda não estão disponíveis ao público. No entanto, planejamos lançar em breve uma versão pública v1.0, que estará disponível para todos pelo Rubygems.

Nas próximas postagens, falaremos sobre algumas das ferramentas mencionadas acima, que criamos para manter nossa documentação e as especificações da API aberta em alto nível.