Créez et maintenez rapidement de la documentation sur votre code ou les fonctionnalités que vous avez développées !
Découvrez comment Alex a utilisé les Documents pour permettre à son équipe d'améliorer les fonctionnalités plus rapidement.
Rencontrez Alex
Alex est un développeur senior dans une entreprise de logiciels basée sur le cloud. Ils constatent que certaines fonctionnalités disposent d'une documentation très limitée.
Alex remarque que l'équipe passe beaucoup de temps à étudier le fonctionnement des fonctionnalités directement à partir du code de leur logiciel. Cela ralentit la capacité de l'équipe à améliorer les fonctionnalités existantes.
Le défi
Les équipes de produit et d'ingénierie travaillent selon un calendrier très serré pour intégrer des fonctionnalités dans le produit. Les développeurs disposent de très peu de temps pour pouvoir créer de la documentation sur les nouvelles fonctionnalités.
L'équipe n'a pas le temps de maintenir la documentation au fur et à mesure que les fonctionnalités sont améliorées et les bugs corrigés.
Certains développeurs récements embauchés sont frustrés par le manque de documentation. Ils ont du mal à apprendre efficacement sur le produit.
Les autres développeurs ont l'impression de passer plus de temps à répondre aux questions qu'à résoudre des problèmes et à écrire un meilleur code.
La solution
Alex travaille à améliorer une fonctionnalité dont la documentation n'est pas très détaillée. Ils décident de créer un document ClickUp avec des informations sur la fonctionnalité comme matériel de référence pour d'autres développeurs.
Créer la structure du document et des pages
Alex décide que chaque fonctionnalité devrait avoir son propre Document. Lorsque l'équipe travaille sur une fonctionnalité, toutes les informations pertinentes se trouvent dans un seul document autonome.
L’utilisation d’une page dans un document permet à l’équipe de trouver rapidement des réponses pertinentes sans chercher et rechercher dans un document séparé.
Alex crée quelques pages dans le document pour structurer le contenu en fonction de ce que l'équipe doit savoir et pourrait rechercher.
-
Résumé du produit
-
Front fin code
-
Code back-end
-
Infrastructure
-
Application mobile
-
Tests et assurance qualité
-
FAQ et dépannage
Conseil : Recherchez des pages spécifiques ou du contenu dans un document en utilisant la fonction de recherche !
En-têtes
Sur chaque page, Alex crée des titres pour que l'équipe de développement sache clairement quelles informations doivent être placées où.
Résumé du produit
-
Présentation du produit
-
Présentation de la fonctionnalité
-
Cas d’utilisation
-
Conception UI
Front End
-
Éléments de l’interface utilisateur
-
Styles
-
Infobulles
Back End
-
Itinéraires API
-
Schéma de base de données
Mobile
-
iOS
-
Android
Tests et assurance qualité
-
Critères d'acceptation
-
Tests automatisés QA
Mise en page
Alex utilise une combinaison des options de formatage disponibles dans ClickUp document pour donner à sa documentation une apparence cohérente.
Code en ligne et blocs de code
Alex utilise des accents graves ( `` ) pour formater le texte en tant que code en ligne afin d'afficher des lignes de code uniques, comme le montre l'exemple ci-dessous :
Pour des extraits de code plus longs, Alex utilise la mise en forme de bloc de code ( /co ) comme illustré ci-dessous :
Options de formatage de bloc de code
Configurez votre bloc de code pour utiliser le langage de codage de votre choix !
-
Passez la souris sur le coin supérieur droit
-
Sélectionner votre langue préférée
Liez et intégrez du contenu
Le document d'Alex contient maintenant du texte, quelques captures d'écran et des extraits de code utiles.
Cela semble bien, mais le résumé du produit est toujours vide.
L'équipe produit utilise Figma pour concevoir et créer des maquettes de l'interface utilisateur. Alex utilise la commande slash /figma pour intégrer le design mis à jour de la fonctionnalité directement sur la page de résumé du produit.
Alex utilise la mention @@ pour faire référence à la tâche Épique sur la feuille de route de l'équipe.
Créer un modèle
Alex enregistre le plan du document comme un modèle pour que l'équipe puisse rapidement et facilement créer un document avec les sous-pages et les titres pour d'autres fonctionnalités.
-
Cliquez sur l'icône des paramètres du Document dans la barre latérale droite
-
Sélectionnez
Enregistrer en tant que modèle
Alex remplit un document exemple en utilisant le modèle afin que l'équipe dispose d'un standard de référence pour la documentation à utiliser comme exemple.
Alex crée un nouveau document à partir du modèle, le complète et le partage avec l'équipe.
Preuve de concept
Alex présente le concept de modèle de document à l'équipe d'ingénierie lors de la prochaine réunion d'équipe. Les autres développeurs adorent l'exemple détaillé de documentation d'Alex !
L'équipe s'inquiète du temps que cela pourrait prendre pour remplir les détails. Alex les met au défi de choisir une fonctionnalité, afin qu'ils puissent montrer à tous à quelle vitesse il est possible de créer de la documentation.
L'équipe décide d'une fonctionnalité. Alex crée un Document, applique le modèle en utilisant la commande slash /temp, et partage le lien avec tous les participants à l'appel.
Quelques développeurs se lancent et commencent à modifier le document en collaboration avec Alex. Tout le monde remplit la page et les sections qu’il connaît le mieux.
L'ensemble de l'équipe est agréablement surpris lorsque, après seulement 20 minutes, ils ont créé un brouillon assez complet de la documentation.
Le résultat
L'équipe accepte de tester le modèle et la documentation d'Alex. Dans leur sprintsuivante, quelques développeurs passent 30 minutes à remplir la documentation de la fonctionnalité phare.
La documentation n'est pas tout à fait terminée. Il y a un plan approximatif avec juste assez de détails pour aider les autres développeurs à commencer à comprendre et à améliorer la fonctionnalité.
Après quelques semaines, l'habitude de rédiger de la documentation est devenue une partie importante des responsabilités de l'équipe d'ingénierie.
Avec quelques ajustements et améliorations apportés au modèle d'Alex, le temps consacré à la création et à la maintenance de la documentation diminue.
Alex envoie un sondage et découvre que :
-
Les nouveaux développeurs se sentent plus en confiance pour travailler avec le code lorsqu’il y a de la documentation disponible
-
Les développeurs expérimentés constatent moins de questions de la part de leurs collègues et des équipes de service client
C’est une grande victoire pour l’équipe d’ingénieurs ! Lors d'un événement d'équipe, Alex reçoit le titre honorifique de « Bibliothécaire résident et gardien du savoir ».