Utiliser Confluence pour créer de la documentation technique de qualité


Publié par
Julie d'ANTIN

21 juin 2017
Cet article a été écrit par Thomas Walker, rédacteur technique chez K15t Software

Créer une documentation de qualité est un projet collaboratif qui implique non seulement des rédacteurs techniques, des ingénieurs, des responsables produit et l’équipe de support client. Un rédacteur technique averti vous le dira : c’est coordonner cet effort de collaboration entre plusieurs départements qui est le plus grand défi du rédacteur technique en charge du projet. La collaboration inter-département est souvent complexe et chronophage… heureusement, les temps changent et de nouveaux outils de collaboration documentaire font leur apparition.

Chez K15t Software, nous utilisons Confluence pour répondre à ce besoin. Les fonctions de collaboration avancée de Confluence en font un outil idéal pour gérer la création et la mise à jour de documentation technique.

Création de documentation collaborative

Afin de créer une documentation technique de qualité, un rédacteur technique doit savoir collaborer. Il doit constamment se tenir au courant des nouvelles fonctionnalités auprès des ingénieurs, discuter des futurs cas d’utilisation avec les responsables produit et s’intéresser aux problèmes rencontrés les plus fréquemment par les utilisateurs en échangeant avec le support client. Décloisonner l’information et faciliter la communication entre les équipes permet non seulement au rédacteur technique d’accomplir sa mission, mais aussi rend la documentation produite plus précise, informative et utile.

En tant qu’outil de gestion de contenu, Confluence permet aux rédacteurs techniques d’impliquer des collègues de différents départements très simplement. Ses fonctionnalités d’édition, de commentaire, et de partage permettent aux rédacteurs techniques de demander du feedback ou des informations directement depuis la page, le paragraphe ou même le mot correspondant. De par sa simplicité de prise en main, Confluence permet à des collègues, même novices sur la solution, d’apporter leur contribution facilement sans passer du temps à comprendre comment utiliser l’outil et à monter en compétence.

info-request-via-inline-comment

Avec des outils de gestion éditoriale plus traditionnels, demander et recevoir un feedback prend beaucoup de temps – il faut parfois organiser des réunions, relancer les personnes qui doivent approuver un changement, etc. Recevoir ces retours rapidement est vital lorsque l’on a des cycles de livraison fréquents – typiquement dans des environnements de travail agiles. C’est là que Confluence apporte une vraie valeur ajoutée pour les rédacteurs techniques. Quand je suis en train d’écrire une première version de la documentation d’un produit, j’utilise régulièrement des inline comments ou des @-mentions pour demander des informations à nos développeurs. Ils reçoivent ensuite une notification qui leur donne la liberté de répondre dès qu’ils ont un moment. Dans le même temps, je continue de travailler sur le reste de mon brouillon. Les développeurs ont la possibilité de me répondre directement dans ma page Confluence plutôt que de le faire par email ou de m’envoyer un document Word. Cela nous fait gagner à tous du temps et permet de réduire les cycles de mise à jour de la documentation : pas besoin de prévoir une réunion, de l’animer (ce qui est encore plus complexe pour les équipes distribuées sur plusieurs sites), de valider les conclusions, etc.

Un autre effet lié au travail en un environnement agile est que, comme les choses évoluent rapidement, il est difficile de se rappeler les détails d’une discussion datant du mois précédent. Pourtant, se rappeler ces détails est important lorsque l’on édite de la documentation technique. Il m’arrive fréquemment qu’une discussion qui n’impacte pas la version en cours soit importante pour la version suivante. En utilisant les commentaires sur les pages Confluence pour documenter les discussions orales, vous pouvez tracer chacune des décisions prises et qui sont à prendre en compte pour le futur. Tout ce que vous avez à faire pour être certain d’être à jour est de rechercher dans les commentaires ceux qui influencent la version en cours – une bénédiction quand vous avez des contraintes de temps. De plus, s’il reste des questions sans réponse, vous pouvez relancer la discussion directement depuis les commentaires et impliquer les personnes concernées en un clic.

Relecture sans accroc grâce aux commentaires et à l’édition collaborative

Une fois toutes les informations rassemblées et la rédaction terminée, vient le moment de la relecture et de la validation de la documentation pour publication. Encore un processus qui demande de la collaboration. Faire relire la documentation à publier par une deuxième paire d’yeux attentifs est une étape incontournable si l’on veut livrer une documentation de qualité. C’est une excellente manière de relever les erreurs de grammaire et les fautes d’orthographe, ainsi que de tester la documentation avant qu’elle ne soit visible de tous – particulièrement si le relecteur ne maîtrise pas le produit. Il peut ainsi relever les parties qui ne sont pas faciles à comprendre ou qui sont trop complexes. Confluence permet aux relecteurs de faire leurs modifications et commentaires directement là où elles sont nécessaires : dans le texte lui-même.

Si nous utilisions un outil comme Microsoft Word pour réaliser notre documentation technique, nous aurions besoin de faire circuler des fichiers versionnés entre les différentes parties prenantes pour relire et valider le contenu. Ceux qui y ont gouté savent que c’est un processus extrêmement long et frustrant, particulièrement s’il n’y a pas de processus de gestion des versions rigoureux (v2.doc, v2-final.doc, v2-final-FINAL.doc, etc) . Confluence vous montrera toujours la version la plus récente d’une page, y compris les changements et les commentaires ajoutés – vous avez toujours accès au document à jour pour travailler. Voir les changements qui ont été faits ou quels commentaires ont été résolus se fait en un simple clic sur le bouton historique de la page. Vous pouvez alors voir qui a ajouté du texte, supprimé un paragraphe, fait des changements dans la mise en page, etc. Dans le cas où vous vous apercevez qu’une version antérieure de la page était plus aboutie, vous pouvez la restorer sans perdre la trace des changements effectués entre temps.

confluence-page-history

Une autre fonctionnalité que j’adore est l’édition collaborative. Introduite en version 6.0, elle permet à différentes personnes de travailler en même temps sur le même document sans écraser les modifications faites par un autre utilisateur par inadvertence.

Parce que tracer les changements et les modifications est si simple, vous pouvez facilement demander à une troisième personne de relire votre documentation. Elle pourra voir quelles discussions ont déjà eu lieu et ajouter une nouvelle perspective sur les décisions qui ont été prises dans les fils de commentaires.

Publication facile avec Scroll Viewport et Scroll Versions

Publier une documentation technique est une des seules étapes pour laquelle il n’est pas bénéfique d’utiliser une approche collaborative. Mettre en ligne la documentation technique ou l’exporter en PDF doit être une opération rapide, simple et ne pas impliquer de trop nombreuses personnes. Chez K15t Software, nous avons implémenté un processus qui nous permet d’éviter d’avoir besoin de dupliquer le contenu ou qui implique des personnes qui ne sont pas directement responsables de la documentation.

En tant que rédacteur technique, je peux directement publier la documentation écrite dans Confluence vers les pages d’aide en ligne en utilisant l’add-on Scroll Viewport que nous éditons. Cet article de blog (en anglais) montre quelques exemples d’entreprises qui utilisent Scroll Viewport pour publier leur documentation. De plus, en utilisant l’add-on de gestion de versions Scroll Versions avec Scroll Viewport, je n’ai plus besoin de publier un espace de documentation entier à chaque changement. Chaque modification approuvée est dynamiquement publiée dans la bonne version de notre documentation. Nous gagnons du temps et l’expérience utilisateur en est améliorée. 

efficient-publication-tech-docs

Bien que l’étape de la publication ne doive pas être trop collaborative, les révisions visant à améliorer la documentation doivent intégrer le feedback des utilisateurs et de mes collègues. Evidemment, tout le monde aimerait créer la documentation parfaite du premier coup, mais cela arrive rarement. L’amélioration continue est au coeur du métier du responsable de la documentation, et il est important que mes collègues et les utilisateurs puissent partager leurs idées, commentaires et suggestions d’amélioration. J’utilise Confluence pour collecter ce feedback dans des commentaires de page ou des inline comments, ou en liant des tickets JIRA avec de l’information contenu dans certaines pages Confluence. De cette manière, je peux rechercher et extraire des suggestions d’amélioration directement depuis l’endroit où j’écrirai la prochaine version. Pratique, non?

Les processus collaboratifs requièrent des outils collaboratifs 

Créer et maintenir de la documentation technique est un processus collaboratif. Dès lors, l’utilisation d’un outil de gestion de contenu collaboratif et moderne s’impose comme un véritable besoin. Si vous souhaitez essayer Confluence gratuitement, rendez-vous sur le site Atlassian pour évaluer le produit (évaluation gratuite pendant 7 jours en version Cloud et 30 jours en version serveur). Vous pourrez voir par vous même combien il permet à toutes les équipes impliquées de gagner en productivité et à quel point sa prise en mains est simple.


 

Pour en savoir plus sur les add-ons Scroll pour Confluence, n’hésitez pas à nous contacter.