Vous cherchez à rationaliser votre processus de documentation produit sans nécessiter d'expertise technique ? Apidog offre une solution complète qui permet aux chefs de produit et aux équipes opérationnelles de collaborer de manière transparente pour créer, gérer et publier une documentation professionnelle. Grâce à son interface intuitive, ses fonctionnalités de collaboration en temps réel et sa publication sans maintenance, Apidog transforme la manière dont les équipes abordent les flux de travail de documentation.
Chaque produit a besoin de sa propre documentation. Même si votre produit est une application grand public avec une conception d'interaction très intuitive et simple, il y aura toujours des domaines qui nécessiteront plus d'explications, mais qui ajouteraient de la complexité s'ils étaient présentés directement dans l'interface du produit. Par conséquent, la gestion, la maintenance et la publication de la documentation sont des préoccupations cruciales pour chaque produit.
Lors de l'élaboration de la documentation produit, les équipes utilisent généralement des outils de documentation prêts à l'emploi comme Notion, ou des outils de gestion de contenu comme Confluence et CMS, ou des générateurs de documentation comme Docusaurus et Gitbook. Cependant, ces solutions rencontrent souvent les problèmes suivants :
- La documentation nécessite du codage pour être rédigée, avec des coûts élevés. Même après la rédaction de la documentation, l'expérience de lecture réelle est souvent décevante ;
- La documentation implique la collaboration de plusieurs rôles, ce qui rend la gestion des versions difficile et complique la communication des suggestions d'optimisation aux autres ;
- La publication de la documentation finalisée dans l'environnement de production est soit trop simple, soit trop complexe, impliquant potentiellement des processus d'ingénierie difficiles à gérer pour les collègues non techniques, ce qui entraîne des erreurs.
L'équipe Apidog utilisait auparavant Docusaurus pour créer notre documentation. Au fur et à mesure que notre documentation continuait d'évoluer, nous avons également rencontré certains des problèmes mentionnés ci-dessus. Après avoir résumé nos expériences et les leçons apprises, nous avons développé des solutions et les avons intégrées dans Apidog. Désormais, la documentation produit de l'équipe Apidog a été entièrement migrée vers Apidog, la création et la présentation étant entièrement gérées par Apidog.
Je vais partager notre pratique sur la façon de construire la documentation produit via Apidog. Avant cela, si vous voulez examiner de plus près les effets spécifiques de la documentation produit d'Apidog, vous pouvez consulter la documentation d'aide d'Apidog - les commentaires sont les bienvenus.
Contexte
Avant de présenter notre pratique, il y a certains contextes qui doivent être expliqués en premier, afin que chacun puisse mieux comprendre pourquoi nous faisons les choses de cette manière. La documentation produit de notre entreprise est généralement créée en collaboration par les collègues des départements produit et opérations. Le processus principal est le suivant :
Le processus ci-dessus ne nécessite aucune implication de personnel technique - toutes les opérations liées à la documentation produit sont effectuées par les collègues de ces deux départements. Ensuite, je vais expliquer comment accomplir la tâche de création de documentation produit via Apidog selon ce processus.
Processus principal
1. Créer une branche de sprint pour la gestion de contenu et la collaboration
Après le début d'une itération de développement, les collègues des opérations créent une branche d'itération dans Apidog pour y placer tous les documents impliquant des modifications dans l'itération actuelle pour la collaboration, évitant ainsi un impact direct sur la branche principale.
Après la création, les chefs de produit importent les documents existants qui nécessitent des modifications dans cette branche d'itération en fonction des fonctionnalités réellement mises à jour dans l'itération, et créent de nouveaux documents pour les nouvelles fonctionnalités directement dans la branche d'itération. L'opération ici est entièrement cohérente avec l'utilisation des branches d'itération pour la documentation API.
Étant donné que nous avons mis en place une protection sur la branche principale, les modifications directes du contenu des documents dans la branche principale ne sont pas autorisées. Cela signifie que vous ne pouvez pas modifier manuellement le contenu de la documentation publiée que les utilisateurs peuvent voir directement, ce qui rend la documentation produit plus stable et réduit les situations où des modifications aléatoires conduisent à un contenu incorrect vu par les utilisateurs.
2. Utiliser le bel éditeur Markdown pour rédiger chaque document
Les chefs de produit utiliseront Markdown pour rédiger la documentation qui doit être mise à jour dans l'itération actuelle au sein de la branche d'itération. La fonctionnalité Markdown d'Apidog est très puissante, avec divers composants visuels sur lesquels on peut cliquer pour insérer de nombreux styles complexes avec une faible barrière à l'entrée, vous permettant de rédiger facilement de beaux articles sans effort supplémentaire.
En plus de l'insertion visuelle de style MD général, Apidog a ajouté les fonctionnalités spéciales suivantes :
- Insérer des API/documents de projet, permettant aux documents de se lier pour former des chaînes de référence avec une navigation fluide, offrant aux lecteurs une expérience plus agréable et résolvant mieux les besoins et les problèmes des lecteurs - c'est une fonctionnalité très importante.
- Fournir des fonctions d'insertion de ressources riches, telles que des icônes, des blocs de surlignage, des tableaux, des étapes, Mermaid, des vidéos, etc., afin que vous n'ayez pas à passer du temps à trouver des ressources vous-même ou à apprendre la syntaxe de style MD pour rendre les documents plus attrayants.
3. Les collègues du produit/opérations collaborent pour peaufiner les documents
Une fois que les chefs de produit ont rédigé la version initiale des documents dans la branche d'itération, pour améliorer la qualité, la clarté et l'utilité pour l'utilisateur, ils transmettent les documents aux collègues des opérations pour qu'ils les lisent du point de vue de l'utilisateur et fournissent des suggestions de modification pour les peaufiner.
C'était auparavant la partie la plus chronophage et la plus laborieuse, nécessitant une collaboration mutuelle entre les deux parties, l'une expliquant ses idées et fournissant des suggestions de modification spécifiques pour certaines parties ; puis l'autre partie recevant, comprenant et effectuant réellement les modifications. Pendant le processus d'aller-retour, il y avait souvent divers problèmes comme des malentendus, des modifications incorrectes et des différences de contenu entre les versions de documents, ce qui entraînait une très faible efficacité.
Maintenant, avec Apidog, les deux parties peuvent directement apporter des modifications aux documents, avec des notifications de message en temps réel poussées vers la messagerie instantanée lorsque des modifications sont effectuées, permettant aux autres d'entrer immédiatement dans le document et de voir facilement les modifications spécifiques, améliorant considérablement l'efficacité de la collaboration. Voici les étapes spécifiques :
- Les chefs de produit créent la version initiale des documents. Après que le personnel des opérations a vu la notification, il lit le document et apporte directement des modifications au contenu qu'il souhaite modifier dans ce document.
- Les modifications déclenchent automatiquement des notifications lors de l'enregistrement, envoyant des cartes de message de modification au groupe de messagerie instantanée préconfiguré. Après que les membres du groupe ont vu les cartes de message de résumé des modifications, ils peuvent cliquer sur le lien de notification pour entrer dans le document pertinent en un clic.
- Grâce à l'historique des modifications, comparez les différences en sélectionnant la version actuelle et la version originale pour visualiser facilement les modifications de l'autre partie et décider comment ajuster le document. Vous pouvez choisir de ne pas accepter les suggestions et de restaurer la version originale, ou d'accepter les modifications et de conserver la dernière version.
Les équipes produit et opérations répètent les étapes ci-dessus jusqu'à ce que le contenu du document soit peaufiné et qu'une version approuvée par tous soit déterminée.
4. Préparation et révision avant la publication officielle du document
Pour garantir que le contenu et les captures d'écran du produit dans les documents sont entièrement cohérents avec ce que les utilisateurs peuvent accéder, nous recommandons de prendre des captures d'écran sur l'environnement de production du produit. Cela permet également de vérifier que les nouvelles fonctionnalités lancées dans l'environnement de production fonctionnent correctement. Une fois que le personnel des opérations utilise les nouvelles fonctionnalités en ligne et prend des captures d'écran, il les ajoute aux articles.
Les opérations confirment les documents de contenu complétés de cette itération, les sélectionnent et soumettent une demande de fusion (MR) pour fusionner dans la branche principale.
Le responsable des opérations ou d'autres administrateurs de projet examinent le contenu du document à publier, confirment qu'il est correct, puis choisissent de fusionner dans la branche principale.
Une fois la fusion terminée, lorsque les utilisateurs accèdent aux documents publiés, ils peuvent voir le contenu le plus récent fusionné dans la branche principale.
Autres avantages
En plus des capacités déjà présentées, Apidog possède également les fonctionnalités suivantes en termes de publication de documents pour aider chacun à créer des sites de documentation produit qui répondent mieux à leurs besoins.
1. Définir des styles de site de documentation globale qui correspondent au style du produit/de l'entreprise
Vous pouvez définir le style général du site de documentation publié, rendant le style de l'ensemble du site web plus conforme à l'identité de votre entreprise, et ajouter plus de ressources connexes et de liens de contenu d'entreprise pour offrir aux utilisateurs une meilleure expérience.
La documentation d'aide d'Apidog a défini son propre logo et quelques liens de ressources liés à Apidog. Le coin supérieur gauche contient le logo de l'entreprise, le coin supérieur droit contient divers liens de ressources liés à l'entreprise, et la documentation API ouverte qui intéresse davantage les développeurs est également définie dans la documentation produit :
2. Expérience de publication sans maintenance
Dans Apidog, il vous suffit de cliquer sur le bouton "Publier" dans la fonction de publication de documentation pour publier l'ensemble de la documentation sur Internet en un clic afin que vos utilisateurs puissent la lire. Apidog fournit officiellement des domaines à tout le monde, ce qui permet d'économiser beaucoup de travail de maintenance.
Bien sûr, si vous avez besoin de faire en sorte que la documentation ressemble davantage au site web de votre propre entreprise, nous proposons également une fonctionnalité de domaine personnalisé, vous permettant d'utiliser le domaine de votre propre entreprise pour accéder à la documentation.
Vous pouvez également configurer facilement la recherche régulière, la recherche plein texte Algolia, intégrer GA, définir des redirections et d'autres capacités avancées dans les sites de documentation produit publiés avec des opérations simples. Ces configurations ne nécessitent pas que les opérateurs aient des capacités d'ingénierie suffisantes - elles peuvent être facilement configurées en suivant les instructions de l'interface et la documentation d'aide.
3. Multiples paramètres favorables au référencement (SEO)
Apidog génère automatiquement des slugs raisonnables pour les sites de documentation publiés en fonction des paramètres de base afin de mieux permettre aux utilisateurs d'y accéder et de les partager.
Bien sûr, si vous avez des besoins SEO plus avancés, il prend également en charge le slug personnalisé, les méta-données et divers autres paramètres de contenu pour chaque document individuel.
Conclusion
Ce qui précède est la pratique spécifique de l'utilisation d'Apidog pour la maintenance de la documentation produit.
En plus du contenu mentionné ci-dessus, nous pouvons également maintenir la documentation d'aide produit, la documentation développeur et la documentation API dans un seul style et les lier toutes ensemble, offrant une expérience utilisateur encore meilleure. Si votre situation réelle convient, n'hésitez pas à essayer cette pratique et à la recommander à d'autres collègues. Nous espérons que cela pourra apporter des améliorations d'efficacité et de qualité à votre travail de création de documentation produit.