Confluence : 5 fonctionnalités majeures pour la rédaction de votre documentation technique


Publié par
Alexandre ALQUIER

2 février 2011

S’il est indiscutable que le contenu d’une documentation technique en est l’élément le plus important, sa mise en forme l’est presque autant.
Je dirais même plus, l’efficacité de votre documentation est intimement liée à sa lisibilité.
Dans cet article, nous allons découvrir cinq fonctionnalités qui vous permettront d’améliorer significativement la lisibilité et l’efficacité de votre documentation technique sous Confluence.

1. Génération automatique de la table des matières

Vous est-il déjà arrivé de parcourir désespérément une documentation technique à la recherche de l’information souhaitée ? Sûrement.

Alors pour augmenter les chances de vos lecteurs de trouver la bonne information, utilisez dès maintenant la macro {sommaire}.
Elle vous permettra de créer et mettre à jour automatiquement une table des matières basée sur les différents niveaux de titre de votre page Confluence.
Vos lecteurs pourront ainsi naviguer dans la page en parcourant la structure de votre document.
Ils pourront aisément passer outre les sections qui ne les intéressent pas pour accéder directement aux chapitres dont ils ont besoin.

Dans l’exemple ci-dessous, la macro {sommaire} (en anglais {table of content}) est utilisée au début de la page « Release Notes ».
On notera que le titre « Highlights of Confluence 3.4 » a été exclus de la table des matières : un des paramètres de la macro permet en effet de sélectionner les niveaux de titres à inclure dans la table.

Confluence table of contents

2. Mise en avant du contenu grâce aux encadrés personnalisés

Rien n’est plus indigeste à lire qu’une documentation monobloc, vous ne trouvez pas?

Alors essayez la macro {volet} (en anglais {panel}), qui permet d’afficher différents types de contenu dans des encadrés personnalisés.
Elle fonctionne avec les blocs de texte, les images ou encore les vidéos.
Utilisez-la pour mettre en avant certains éléments ou définir des sections dans votre page.

Dans l’exemple ci-dessous, les encadrés servent à séparer les instructions du contenu informatif.
Par défaut la couleur de fond de l’encadré est un gris clair, mais elle est paramétrable tout comme le titre et sa couleur de fond ou encore le type et la couleur de la bordure.

Panel

3. Bandeaux d’information préformatés

Les macros {remarque}, {avertissement}, {info} et {astuce} proposent chacune un bandeau de couleur différent associé à un pictogramme (facultatif).
L’association des deux apporte une signification visuelle au contenu : vert avec une coche pour les astuces, jaune avec un point d’exclamation pour les mises en garde…

Bandeau

4. Eléments à tiroirs

Quand une documentation technique devient un peu fouillis, on aimerait pouvoir masquer des blocs d’informations et les afficher à la demande.

C’est possible avec la macro {expand}, qui fonctionne avec les blocs de texte et les vidéos.
Vous voulez en savoir plus sur un point précis de la documentation ? Il suffit de déplier la boîte !

Expand

Remarque : cette macro n’est pas disponible nativement sous Confluence, mais le code est disponible gratuitement sur le site d’Atlassian.

5. Insertion de contenus multimédia

Avec internet et les contenus multimédias en ligne, la documentation en texte seul appartient au passé !

Exploitez la mise en ligne de la documentation et restez connecté en incluant des contenus multimédia et des vidéos.
La macro {widget connector} permet d’inclure dans des pages Confluence des contenus provenant des sites web les plus populaires.
Vous pourrez ainsi afficher des vidéos YouTube, des messages Twitter, des documents et présentations SlideShare et Google Docs, des formulaires Wufoo…
Et ce ne sont que quelques exemples !

Media

Pour aller plus loin