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.

Présentation d'Alex

Alex est un développeur senior dans une entreprise de logiciels basée sur le cloud. Il constate que certaines fonctionnalités disposent d'une documentation très limitée.

Alex remarque que l'équipe passe beaucoup de temps à comprendre le fonctionnement des fonctionnalités directement depuis le code du logiciel. Cela ralentit la capacité de l'équipe à améliorer les fonctionnalités existantes.

Le défi

Les équipes produit et technique travaillent selon un calendrier très serré pour livrer les fonctionnalités dans le produit. Les développeurs disposent de très peu de temps pour 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 qu'une fonctionnalité évolue et que les bugs sont corrigés.

Quelques développeurs moins expérimentés sont frustrés par le manque de documentation. Ils ont du mal à apprendre à connaître le produit efficacement.

D'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 à l'amélioration d'une fonctionnalité qui ne dispose pas d'une bonne documentation. Il décide de créer un Document ClickUp contenant des informations sur la fonctionnalité, comme support de référence pour les autres développeurs.

Créer le document et la structure des pages

Alex décide que chaque fonctionnalité doit avoir son propre Document. Lorsque l'équipe travaille sur une fonctionnalité, toutes les informations pertinentes se trouvent dans un document autonome.

L'utilisation de pages au sein d'un Document permet à l'équipe de trouver rapidement les réponses pertinentes sans avoir à chercher dans des Documents séparés.

Alex crée quelques pages dans le Document pour structurer le contenu en fonction de ce que l'équipe doit savoir et de ce qu'elle pourrait rechercher.

1. Résumé du produit
2. Code frontal
3. Code dorsal
4. Infrastructure
5. Application mobile
6. Tests et assurance qualité
7. FAQ et dépannage

Titres

Sous chaque page, Alex définit des titres pour que l'équipe de développement sache clairement quelles informations vont où.

Résumé du produit

• Brief produit
• Description de la fonctionnalité
• Cas d'utilisation
• Conception de l'interface

Frontal

• Éléments d'interface
• Styles
• Infobulles

Dorsal

• Routes API
• Schéma de base de données

Mobile

• iOS
• Android

Tests et assurance qualité

• Critères d'acceptation
• Tests automatisés d'assurance qualité

Mise en forme

Alex combine les options de mise en forme disponibles dans ClickUp Documents pour donner à sa documentation un aspect cohérent.

Code en ligne et blocs de code

Alex utilise des guillemets inversés ( ` ) pour mettre du texte en forme en tant que code en ligne et afficher des lignes de code individuelles, comme illustré dans l'exemple ci-dessous :

Pour les extraits de code plus longs, Alex utilise la mise en forme par blocs de code ( /co ), comme illustré ci-dessous :

Options de mise en forme des blocs de code

Configurez votre bloc de code pour utiliser le langage de programmation de votre choix !

1. Survolez le coin supérieur droit
2. Sélectionnez le langage de votre choix

Lier et incorporer du contenu

Le Document d'Alex contient maintenant du texte, quelques captures d'écran et des extraits de code utiles.

Le résultat est satisfaisant, mais le résumé du produit est encore vide.

L'équipe produit utilise Figma pour concevoir et créer des maquettes de l'interface utilisateur. Alex utilise la commande Slash /figma pour incorporer la conception mise à jour de la fonctionnalité directement dans la page de résumé du produit.

Alex utilise la mention @@ pour créer un lien vers la tâche Epic dans la feuille de route de l'équipe.

Créer un modèle

Alex enregistre la structure du Document en tant que Modèle afin que l'équipe puisse créer rapidement et facilement un Document avec les sous-pages et les titres pour d'autres fonctionnalités.

1. Cliquez sur l'icône des paramètres du Document dans la barre latérale droite
2. Sélectionnez Enregistrer comme modèle

Alex remplit un exemple de Document à l'aide du modèle afin que l'équipe dispose d'un exemple de référence en matière de documentation.

Alex crée un nouveau Document basé sur le 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 technique lors de la prochaine réunion d'équipe. Les autres développeurs adorent l'exemple de documentation détaillé d'Alex !

L'équipe s'interroge sur le temps qu'il faudrait pour renseigner tous les détails. Alex les invite à choisir une fonctionnalité pour montrer à tout le monde à quelle vitesse il est possible de créer de la documentation.

L'équipe choisit une fonctionnalité. Alex crée un Document, applique le modèle à l'aide de la commande Slash /temp et partage le lien avec tous les participants à l'appel.

Quelques développeurs rejoignent la session et commencent à modifier le Document de manière collaborative avec Alex. Chacun complète les pages et les sections qu'il connaît le mieux.

L'ensemble de l'équipe est agréablement surpris de constater qu'après seulement 20 minutes, ils ont créé une ébauche de documentation assez complète.

Le résultat

L'équipe accepte de tester le modèle et la documentation d'Alex. Lors de leur prochain Sprint, quelques développeurs consacrent 30 minutes à la rédaction de la documentation pour la fonctionnalité phare.

La documentation n'est pas tout à fait terminée. Il s'agit d'une ébauche avec juste assez de détails pour aider les autres développeurs à commencer à comprendre et à améliorer la fonctionnalité.

Après quelques semaines, la rédaction de documentation est devenue une partie importante des responsabilités de l'équipe technique.

Grâce à 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 développeurs moins expérimentés se sentent plus à l'aise pour travailler avec le code lorsque de la documentation est disponible
• Les développeurs expérimentés reçoivent moins de questions de la part de leurs collègues et des équipes du support client

C'est une grande victoire pour l'équipe technique ! Lors d'un événement d'équipe, Alex reçoit le titre honorifique de « Bibliothécaire résident et gardien du savoir ».