Procurando otimizar seu processo de documentação de produtos sem exigir conhecimento técnico? O Apidog oferece uma solução abrangente que capacita gerentes de produto e equipes de operações a colaborar perfeitamente na criação, gerenciamento e publicação de documentação profissional. Com sua interface intuitiva, recursos de colaboração em tempo real e publicação com manutenção zero, o Apidog transforma a forma como as equipes abordam os fluxos de trabalho de documentação.
Todo produto precisa de sua própria documentação. Mesmo que seu produto seja um aplicativo voltado para o consumidor com um design de interação muito intuitivo e simples, ainda haverá áreas que precisam de mais explicação, mas que adicionariam complexidade se apresentadas diretamente na interface do produto. Portanto, o gerenciamento, a manutenção e a publicação de documentos são preocupações cruciais para todo produto.
Ao construir a documentação do produto, as equipes geralmente usam ferramentas de documentação prontas para uso, como Notion, ou ferramentas de gerenciamento de conteúdo, como Confluence e CMS, ou geradores de documentação, como Docusaurus e Gitbook. No entanto, essas soluções frequentemente encontram os seguintes problemas:
- A documentação requer codificação para ser escrita, com altos custos. Mesmo depois de a documentação ser escrita, a experiência de leitura real muitas vezes fica aquém das expectativas;
- A documentação envolve a colaboração de várias funções, dificultando o gerenciamento de versões e tornando difícil comunicar sugestões de otimização a outras pessoas;
- Publicar a documentação final no ambiente de produção é muito simples ou muito complexo, podendo envolver processos de engenharia que são difíceis para colegas não técnicos lidarem, levando a erros.
A equipe do Apidog usava anteriormente o Docusaurus para criar nossa documentação. À medida que nossa documentação continuava a iterar, também encontramos alguns dos problemas mencionados acima. Depois de resumir nossas experiências e lições aprendidas, desenvolvemos soluções e as integramos ao Apidog. Agora, a documentação do produto da equipe Apidog foi completamente migrada para o Apidog, com toda a criação e apresentação sendo tratadas pelo Apidog.
Vou compartilhar nossa prática de como construir documentação de produto através do Apidog. Antes disso, se você quiser dar uma olhada mais de perto nos efeitos específicos da documentação de produto do Apidog, pode conferir a documentação de ajuda do Apidog – o feedback é bem-vindo.
Contexto
Antes de apresentar nossa prática, há alguns contextos que talvez precisem ser explicados primeiro, para que todos possam entender melhor por que fazemos as coisas dessa maneira. A documentação de produto de nossa empresa é geralmente criada em colaboração por colegas dos departamentos de produto e operações. O processo principal é o seguinte:
O processo acima não requer envolvimento de pessoal técnico – todas as operações relacionadas à documentação do produto são concluídas por colegas desses dois departamentos. A seguir, explicarei como concluir a tarefa de construir a documentação do produto através do Apidog de acordo com este processo.
Processo Principal
1. Crie um Ramo de Sprint para Gerenciamento de Conteúdo e Colaboração
Após o início de uma iteração de desenvolvimento, os colegas de operações criam um ramo de iteração no Apidog para colocar todos os documentos que envolvem alterações na iteração atual dentro deste ramo para colaboração, evitando impacto direto no ramo principal.
Após a criação, os gerentes de produto importam documentos existentes que precisam de modificação para este ramo de iteração com base nos recursos realmente atualizados na iteração, e criam novos documentos para novos recursos diretamente no ramo de iteração. A operação aqui é completamente consistente com o uso de ramos de iteração para documentação de API.
Como definimos proteção no ramo principal, alterações diretas no conteúdo do documento no ramo principal não são permitidas. Isso significa que você não pode modificar manualmente o conteúdo na documentação publicada que os usuários podem ver diretamente, tornando a documentação do produto mais estável e reduzindo situações em que alterações aleatórias levam a conteúdo incorreto sendo visto pelos usuários.
2. Use o Belo Editor Markdown para Escrever Cada Documento
Os gerentes de produto usarão Markdown para escrever a documentação que precisa ser atualizada na iteração atual dentro do ramo de iteração. A funcionalidade Markdown do Apidog é muito poderosa, com vários componentes visuais que podem ser clicados para inserir muitos estilos complexos com uma baixa barreira de entrada, permitindo que você escreva facilmente artigos bonitos sem gastar esforço extra.
- Insira APIs/documentos do projeto, permitindo que os documentos se liguem formando cadeias de referência com navegação perfeita, proporcionando aos leitores uma experiência mais fluida e resolvendo melhor as necessidades e problemas dos leitores – este é um recurso muito importante.
- Forneça funções ricas de inserção de recursos, como Ícones, blocos de destaque, tabelas, etapas, Mermaid, vídeos, etc., para que você não precise gastar tempo encontrando recursos por conta própria ou aprendendo a sintaxe de estilo MD para fazer os documentos parecerem melhores.
3. Colegas de Produto/Operações Colaboram para Polir Documentos
Depois que os gerentes de produto escrevem a versão inicial dos documentos no ramo de iteração, para melhorar a qualidade, clareza e utilidade do documento para o usuário, eles entregam os documentos aos colegas de operações para que leiam da perspectiva do usuário e forneçam sugestões de modificação para o polimento.
Esta costumava ser a parte mais demorada e trabalhosa, exigindo colaboração mútua entre ambas as partes, com uma parte explicando suas ideias e fornecendo sugestões de modificação específicas para certas partes; então a outra parte recebendo, compreendendo e realmente fazendo as alterações. Durante o processo de idas e vindas, frequentemente havia vários problemas como mal-entendidos, alterações incorretas e diferenças de conteúdo entre as versões do documento, levando a uma eficiência muito baixa.
Agora, usando o Apidog, ambas as partes podem fazer modificações diretamente nos documentos, com notificações de mensagens em tempo real enviadas para o IM quando as alterações são feitas, permitindo que outros entrem imediatamente no documento e vejam facilmente as alterações específicas, melhorando muito a eficiência da colaboração. Aqui estão os passos específicos:
- Os gerentes de produto criam a versão inicial dos documentos. Depois que o pessoal de operações vê a notificação, eles leem o documento e fazem modificações diretamente no conteúdo que desejam alterar dentro deste documento.
- As modificações acionam automaticamente notificações ao salvar, enviando cartões de mensagem de alteração para o grupo de IM pré-configurado. Depois que os membros do grupo veem os cartões de mensagem de visão geral das alterações, eles podem clicar no link de notificação para entrar no documento relevante com um clique.
- Através do histórico de modificações, compare as diferenças selecionando a versão atual e a versão original para visualizar facilmente as modificações da outra parte e decidir como ajustar o documento. Você pode optar por não aceitar sugestões e restaurar para a versão original, ou aceitar modificações e manter a versão mais recente.
As equipes de produto e operações repetem os passos acima até que o conteúdo do documento seja polido e uma versão que todos aprovem seja determinada.
4. Preparação e Revisão Antes da Publicação Oficial do Documento
Para garantir que o conteúdo e as capturas de tela do produto nos documentos sejam completamente consistentes com o que os usuários podem acessar, recomendamos tirar capturas de tela no ambiente de produção do produto. Isso também permite verificar se as novas capacidades lançadas no ambiente de produção estão funcionando corretamente. Depois que o pessoal de operações usa novos recursos online e tira capturas de tela, eles as adicionam aos artigos.
As operações confirmam os documentos de conteúdo concluídos desta iteração, selecionam-nos e enviam uma solicitação de MR para mesclar no ramo principal.
O gerente de operações ou outros administradores de projeto revisam o conteúdo do documento a ser publicado, confirmam que está correto e, em seguida, optam por mesclar no ramo principal.
Após a conclusão da mesclagem, quando os usuários acessam os documentos publicados, eles podem ver o conteúdo mais recente mesclado no ramo principal.
Outras Vantagens
Além das capacidades já introduzidas, o Apidog também possui as seguintes funcionalidades em termos de publicação de documentos para ajudar a todos a construir sites de documentação de produto que melhor atendam às suas necessidades.
1. Defina Estilos Gerais do Site de Documentação que Correspondam ao Estilo do Produto/Empresa
Você pode definir o estilo geral do site de documentação publicado, tornando o estilo de todo o site mais alinhado com o tom da sua empresa, e adicionando mais recursos relacionados e links de conteúdo da empresa para proporcionar aos usuários uma experiência melhor.
A documentação de ajuda do Apidog definiu seu próprio logotipo e alguns links de recursos relacionados ao Apidog. O canto superior esquerdo contém o logotipo da empresa, o canto superior direito contém vários links de recursos relacionados à empresa, e a documentação da API aberta que os desenvolvedores mais se importam também está configurada dentro da documentação do produto:
2. Experiência de Publicação com Manutenção Zero
No Apidog, você só precisa clicar no botão "Publicar" no recurso de publicação de documentação para publicar toda a documentação na internet com um clique para que seus usuários a leiam. O Apidog fornece oficialmente domínios para todos usarem, economizando muito trabalho de manutenção.
Claro, se você precisar que a documentação se pareça mais com o site da sua própria empresa, também oferecemos a funcionalidade de domínio personalizado, permitindo que você use o domínio da sua própria empresa para acessar a documentação.
Você também pode configurar facilmente a pesquisa regular, pesquisa de texto completo Algolia, integrar GA, configurar redirecionamentos e outras capacidades avançadas em sites de documentação de produto publicados com operações simples. Essas configurações não exigem que os operadores tenham capacidades de engenharia suficientes – elas podem ser facilmente configuradas seguindo a orientação da interface e a documentação de ajuda.
3. Múltiplas Configurações Amigáveis ao SEO
O Apidog gera automaticamente Slugs razoáveis para sites de documentação publicados com base em configurações básicas para permitir que os usuários os acessem e compartilhem melhor.
Claro, se você tiver necessidades de SEO mais avançadas, ele também suporta Slug personalizado, Meta Data e várias outras configurações de conteúdo para cada documento individual.
Conclusão
Acima está a prática específica de usar o Apidog para a manutenção da documentação do produto.
Além do conteúdo mencionado acima, também podemos manter a documentação de ajuda do produto, a documentação do desenvolvedor e a documentação da API em um único estilo e vinculá-las, proporcionando uma experiência de usuário ainda melhor. Se sua situação atual for adequada, sinta-se à vontade para experimentar esta prática e recomendá-la a outros colegas. Esperamos que isso possa trazer algumas melhorias de eficiência e qualidade para o seu trabalho de construção de documentação de produto.