Cada serviço prestado pela Selectel pode ser gerenciado em sua conta pessoal - painel de controle . Muitos de nossos produtos também podem ser controlados por meio de solicitações de API. As instruções do produto e a documentação da API estão disponíveis em uma única central de ajuda .
A ideia principal do centro de ajuda é fornecer aos nossos clientes a oportunidade de encontrar respostas independentes para a maioria de suas perguntas sobre os serviços da Selectel a qualquer momento que lhes seja conveniente.
A seguir, falaremos sobre como mudamos a abordagem de preparação da documentação e atualizamos a aparência da base de conhecimento.
A implementação técnica da base de conhecimento e seu componente visual há três anos cobriu totalmente todas as necessidades de um livro de referência com informações. Mas, ao longo do tempo, a empresa não parou, mas tem se desenvolvido ativamente, tanto lançando novos serviços quanto desenvolvendo os existentes.
Há cerca de um ano, percebemos que a ajuda online existente não atendia aos requisitos de nossos clientes:
- o menu de navegação cresceu como uma árvore frutífera que não conhece os cuidados de um jardineiro;
- a busca deixou de ser conveniente;
- o design visual foi gradualmente desatualizado.
Anteriormente, a documentação para a API de nossos produtos não estava disponível publicamente - alguns foram postados no painel de controle my.selectel.ru , alguns foram emitidos mediante solicitação e alguns foram completamente descritos em um formato de texto, que foi mantido atualizado muito problemático. Agora, conhecimento da automação da infraestrutura de TI e interação com o backend dos serviços Selectel na guia API Documentation .
Uma pequena excursão ao passado
Há dez ou quinze anos, poucas empresas produtoras de software na Rússia podiam se orgulhar de ter uma ajuda online. Os manuais de operação foram escritos em formato Word usando estilos em constante mudança, tentando aplicar os GOSTs criados nos anos 70 do século 20 aos requisitos modernos e em constante mudança.
O meme ainda é popular entre os escritores técnicos:
Até hoje, existem empresas que já podem se orgulhar de uma interface de site conveniente, mas sua documentação permanece no nível de "instruções de download em formato pdf para 45 folhas".
Em grandes empresas, a base de conhecimento está fortemente associada ao suporte técnico. Em um mundo esférico ideal no vácuo, o usuário deve ser capaz de encontrar de forma independente 80% das respostas para suas perguntas, sem entrar em contato com o suporte técnico.
O portal com documentação não traz nenhum lucro óbvio, mas pode economizar tempo de suporte técnico devido ao script:
- O usuário solicitou o serviço.
- Confrontado com momentos não óbvios durante a configuração.
- Queria entrar em contato com o suporte técnico.
- Fui até a base de conhecimento e encontrei as informações de que precisava.
- Não contate o suporte técnico.
- Lucro!)
Freqüentemente, há uma opinião de que as informações de ajuda apenas ajudam os usuários a entender os serviços depois de conectados. Isso provavelmente acontecia na época em que eram publicados livros impressos com informações sobre como trabalhar no Windows. Mas agora é tão importante mostrar abertamente aos usuários em potencial como o serviço funciona antes da compra.
A maioria das empresas de software desenvolve APIs para uso interno e clientes em algum momento. As empresas compartilham um conjunto de entradas lançando APIs públicas para permitir que os clientes integrem seus serviços aos produtos da empresa.
Muitas tarefas personalizadas podem ser automatizadas, incluindo o uso de blocos de código prontos como um construtor para criar a infraestrutura mais amigável. Mas trechos de código sem explicações sobre o que é, o que faz e como usá-lo são de pouca utilidade - você não terá força bruta para descobrir o que são métodos e quais dados eles esperam inserir.
- O que precisa ser feito para tornar a API pública agradável de usar?Como documentação para a API, eles geralmente fornecem um exemplo mínimo de interação, que descreve os métodos (também chamados de terminais) e fornece respostas do serviço. Por exemplo, usando a API Kubernetes, você pode automatizar o trabalho com clusters e nós no Kubernetes gerenciado .
- Anexe a documentação!
Quais tarefas estavam diante de nós
Nossa solução visual parou de facilitar a localização dos artigos de que precisávamos e o menu existente se tornou uma "planilha" ilegível. Documentação ilegível é tão ruim quanto textos irrelevantes. As pessoas estão acostumadas a ler materiais bem elaborados. Blogs, redes sociais, mídia - todo o conteúdo é apresentado não apenas bonito, mas também fácil de ler, agradável à vista. Atualmente, os requisitos de UX e UI não podem ser ignorados, especialmente para uma grande variedade de textos.
Com o desenvolvimento de tecnologias para o design visual de sites, percebemos que a aparência de nossa base de conhecimento está desatualizada. Usar apenas âncoras e listas em artigos da base de conhecimento não ajudou. Foi necessário revisar toda a estrutura da documentação e do mecanismo de busca.
Problemas comuns com documentação
Geralmente ausente ou ninguém sabe de sua existência.A
instrução que não pode ser encontrada não é melhor do que a instrução que não existe.
Resolvemos este problema da seguinte forma - começamos a adicionar links para artigos úteis em nossa lista de mala direta mensal, adicionar transições nas páginas de produtos do site e também configurar notificações para todos os funcionários da empresa interessados através de um canal especial no mensageiro corporativo.
Desatualizado e não atualizado a tempo
O processo de documentação não está embutido no desenvolvimento do produto, a documentação é feita em uma base de sobras.
Em nosso caso, o gerente de produto também tem a tarefa de documentar essa nova funcionalidade enquanto trabalha na nova funcionalidade.
A documentação é complexa e mal organizada, é mais fácil pedir ao suporte técnico como resolver o problema.Escrever
documentação por causa da documentação é inútil, deve ser facilmente acessível. Quanto mais opções para localizar um documento, melhor.
Revisamos completamente o design das seções de nossa base de conhecimento, em alguns casos os modelos universais não funcionavam, então tivemos que interagir ativamente com todas as partes interessadas, seja o gerente de produto, o suporte técnico ou a equipe de desenvolvimento front-end.
Movendo a documentação da API para o espaço público
Um dos problemas com o uso de documentação de API gerada em OpenAPI, Swagger ou outra ferramenta de geração é a integração complexa com o resto do site. É necessário que os usuários tenham acesso descomplicado a todas as instruções e artigos - é inconveniente se os terminais forem exibidos em uma visualização e as descrições de texto dos mesmos processos forem exibidas em outra página.
Mantendo uma única imagem visual
Ao criar um único centro de ajuda, precisávamos manter uma exibição consistente de instruções e especificações, usando um monte de "git + markdown + swagger".
Como funciona agora
Implementação técnica
A base de conhecimento foi originalmente construída em torno de uma combinação de Confluence e um gerador de página estática.
Abandonamos o Confluence e passamos para Documentation-as-Code. Agora, todo o código-fonte da base de conhecimento é composto no formato Markdown e armazenado no sistema de armazenamento de versão Git. Um site de base de conhecimento é construído a partir do repositório usando o Hugo Static Site Generator.
O site é gerado a partir dos arquivos contidos no branch master do repositório Git. Os dados podem ser atualizados apenas por meio de uma solicitação pull, que permite verificar todas as novas seções da documentação antes de serem publicadas no domínio público. Esse sistema também facilita a abordagem para fazer edições - os funcionários da empresa sempre podem criar uma filial e adicionar todas as alterações necessárias.
Mais sobre documentação como código
O princípio de "documentação como código" implica o uso das mesmas ferramentas para escrever documentação e para criar código:
- linguagens de marcação de texto;
- sistemas de controle de versão;
- revisão de código.
O principal objetivo dessa abordagem é criar condições para o trabalho conjunto de toda a equipe no resultado final - uma base de conhecimento completa e instruções para o uso de serviços de produtos individuais.
Trabalhar com arquivos swagger
Os desenvolvedores de produtos Selectel criam uma API e carregam comentários para o código no formato swagger - este é um arquivo de texto no formato * .yaml que pode ser usado como um código. Quando a API é atualizada, o arquivo swagger também é atualizado, o que torna mais fácil atualizar a documentação.
A seguinte solução técnica é usada para a documentação da API:
- repositório git com arquivos de especificação swagger no formato * .yaml, agrupados por produto;
- repositório git com traduções de especificações swagger no formato * .json;
- repositório git com arquivos no formato * .md;
- os arquivos no formato * .md contêm descrições de texto e agrupados em tags de descrição de endpoint especiais que são extraídas do repositório git com arquivos no formato * .json;
- Hugo gerador de sites estáticos.
Além da estrutura do repositório, foram desenvolvidas regras para trabalhar com ele:
- um guia de estilo foi preparado - uma lista de verificação para arquivos swagger, que os desenvolvedores verificam ao atualizar as especificações da API;
- o branch master do repositório git com arquivos no formato * .md reflete o estado das especificações atuais e está de fato em produção;
- O pull-Request para o branch master é executado quando as atualizações são lançadas na produção.
Componente visual
A primeira etapa foi revisar a navegação e criar regras de acordo com as quais as seções da base de conhecimento seriam formadas. Juntamente com designers de UX, preparamos uma arquitetura de informação. A estrutura deve ser o mais transparente possível para que o leitor não pense: "Onde você encontra este artigo?" Para resumir, existem duas abordagens:
- Da interface. O conteúdo duplica as seções do painel (separadamente para serviços). Esse era o caso na versão anterior da base de conhecimento.
- De tarefas. Os títulos dos artigos e seções refletem as tarefas dos usuários.
Para simplificar a estrutura, usamos uma combinação dessas duas abordagens. Mesmo nas versões mais novas do painel de controle com UX e UI bem pensados, é necessário explicar pelo menos os termos, já que nossos produtos são tecnicamente complexos e os usuários são muito diferentes.
Além de atualizar o índice, aprimoramos a pesquisa e a localização atual. "Breadcrumbs" é o caminho do usuário para a página atual com a capacidade de retornar a qualquer nível. Na versão anterior da base de conhecimento, era impossível acessar o índice analítico e isso era inconveniente, portanto, na nova versão, nós o corrigimos.
Cada empresa faz a documentação da API de acordo com sua própria visão de estilo, estrutura e senso de beleza. Se abrirmos 4-5 APIs públicas de diferentes empresas, então, sem dúvida, seremos capazes de capturar alguns pontos comuns: estrutura, exemplos de código volumosos e realce de sintaxe, páginas longas. No entanto, todos os exemplos terão características especiais. Por exemplo, a localização de descrições de terminal é rara, enquanto a estrutura das descrições de terminal geralmente parece a mesma.
Várias recomendações para estruturar a documentação da API:
Endpoints de agrupamento
Além de fornecer informações para cada endpoint, se houver muitos endpoints, é desejável agrupá-los. A longa lista contínua de terminais torna a navegação difícil.
Descrição separada de métodos
Ao usar os métodos GET / POST ao mesmo tempo, apenas um método deve ser descrito em uma linha.
Ou seja, a primeira linha neste caso é a descrição de GET, a segunda linha é a descrição de POST, para evitar confusão.
Automação de fazer alterações
Simplifique fazer alterações sem reformatar manualmente cada seção - no nosso caso, traduzimos apenas o texto do arquivo swagger, sem tocar na marcação, graças à automação desse processo, que nossos especialistas em devops configuraram.
Destaque de sintaxe Os
desenvolvedores amam exemplos de código acima de tudo no mundo, nenhum desenvolvedor reclamará que há muitos exemplos - eles reduzem significativamente o tempo de imersão no produto.
Trabalhar com trechos de código é muito mais conveniente quando diferentes elementos são coloridos apropriadamente, dependendo da linguagem de programação.
Como o realce de código pronto para uso estava disponível apenas para fundos escuros, o desenvolvedor de front-end modificou esta solução com o realce.js para nosso estilo corporativo.
Em vez de uma conclusão
A base de conhecimento atualizada está disponível para os usuários desde março, e a documentação da API está disponível desde o início de agosto.
“- Com a gente, quando você corre muito, certamente se encontra em outro lugar.O que já fizemos é apenas mais um passo para melhorar a base de conhecimento. Iremos adicionar gradualmente novas instruções e documentação às APIs de nossos outros serviços.
“Bem, aqui, você sabe, você tem que correr o mais rápido para ficar no mesmo lugar, e para chegar a outro lugar, você precisa correr duas vezes mais rápido.”
(Lewis Carroll "Alice através do espelho")