Rédaction de documents techniques sur Confluence – partie 1

Si vous suivez un peu l’actualité du blog Atlassian, vous avez certainement remarqué cette série de plusieurs billets qui traite de la rédaction de documents techniques dans Confluence. En tout cas, nous les avons remarqués ; ce sont des billets très bien faits qui ont fortement attiré notre attention. En tant qu’utilisateur de Confluence, et qui plus est pour de la documentation technique, nous les avons trouvés particulièrement intéressants, nous souhaitons donc vous les faire partager.

Convaincus par les performances des solutions wikis pour tout ce qui touche à la documentation technique, nous avons choisi Confluence, alors pourquoi pas vous ?

Nous vous invitons à lire ce premier billet : bien communiquer sur de la documentation technique ; comment et pourquoi ?

Faites-nous part de vos commentaires et ne manquez surtout pas la suite !


Il y a encore quelques temps, quasiment personne n’envisageait de faire partager sa documentation technique sur un wiki et pourtant cela a ses avantages …

Les wikis sont « funs », mais lorsqu’il s’agit de documentation technique, ce sont des outils fiables et sérieux sur lesquels on peut s’appuyer.

Un wiki est capable de gérer une suite de documentation technique sans problème aussi bien qu’un outil de publication classique ou qu’un outil de CMS. Il peut supporter plusieurs versions de documents, le contenu peut facilement être ré-utilisé ou restructuré, il supporte plusieurs versions de documentation du produit, la publication, et plus encore. Découvrons ensemble les forces d’un wiki dans le cadre du partage de la documentation.

  • Un outil parfait pour quelqu'un qui veut écrire de la documentation technique :

Pourquoi ? Parce qu’un wiki vous permet de corriger une erreur, faire une modification en « direct live » dans votre document le plus facilement du monde. Il faut juste ouvrir la page, effectuer votre modification et cliquer sur enregistrer. C’est aussi simple que ça.

Rédiger dans un wiki peut aussi être plus intéressant que ce que peut offrir un éditeur de texte de type HTML ou XML. De nombreux wiki comme Confluence intègrent des éditeurs riches qui facilitent la mise en forme. C’est un avantage qui vous permet de vous concentrer sur la rédaction plutôt que de vous creuser la tête pour trouver une balise mal fermée.

Ce ne sont pas uniquement les processus de rédaction et de publication qui rendent les wikis plus faciles à utiliser. Collecter les informations pour écrire de la documentation technique est souvent un effort collectif entre les managers, les développeurs et l’auteur du document. Un wiki est par définition, l’outil de management collaboratif idéal pour ça. Pouvoir supporter facilement des brouillons pour avoir les meilleurs résultats possibles grâce aux feedbacks constructifs, aux commentaires laissés sur la page ou bien encore par la mise à jour elle-même du brouillon par d’autres utilisateurs permet d’améliorer la qualité de votre documentation. Les feedbacks sont petit à petit incorporés au document comme on le souhaite.

  • Un outil parfait pour les clients

Beaucoup de wikis disposent d’outils de documentation classiques qui aident les utilisateurs à trouver rapidement l’information dont ils ont besoin grâce à de puissants outils de recherche, des tags / labels, des chemins  de navigation, etc…qui sont intégrés dans la solution wiki. Les wikis peuvent aller encore plus loin que ces fonctions pour fournir à leurs utilisateurs des contenus encore plus riches. Exemple : intégrer une vidéo dans votre document. C’est facile, il n’y a pas de procédures compliquées. Vous avez juste à intégrer un diagramme de processus au sein de votre page wiki. Il existe des addons et des plugins qui peuvent être utilisés pour ajouter des fonctionnalités innovantes dans de nombreux wikis.

Quant au souci de pouvoir fournir à vos clients ses documents sous différents formats, pas de problème. Il existe des options d’exportation de documentation : PDF, HTML et XML notamment… Différents styles peuvent aussi être appliqués en fonction du format que l’utilisateur choisit, ce qui permet aux documents d’être personnalisés et  adaptés à une cible définie.

La documentation inscrite dans un wiki peut aussi aider à améliorer le support client. Les équipes de support mettent régulièrement la documentation à jour et en ajoutent de nouvelles de manière à s’assurer que les clients ont accès à une documentation récente et actualisée qui répond à leurs questions. C’est un moyen non négligeable de récupérer des feedbacks clients. Les commentaires ajoutés sur les pages permettent aux équipes de développement de connaitre les problèmes rencontrés avec la documentation ou avec certaines applications.

  • Un outil parfait pour l'entreprise

La dureté de certains commentaires publiés sur votre wiki vous rend nerveux ? Vous ne devriez pas, voyez plutôt le bon côté des choses : les clients répondent aux questions d’autres clients au sein du wiki, des développeurs extérieurs à votre entreprise ajoutent des échantillons de code en vue d’améliorer la qualité de vos documents, certains partenaires insèrent de la documentation... Une documentation bien maintenue sur un wiki encourage à créer une communauté de clients active. Un bon wiki d’entreprise vous met à disposition des outils, comme un gestionnaire de droits d’accès, des filtres antispams ou des CAPTCHA qui permettent à votre communauté d’interagir avec votre documentation en tout sécurité. Plusieurs entreprises ont déjà mis leur documentation dans un wiki ! Voir la liste. Voici une liste de wikis de documentation.

Certains wikis sont plus fonctionnels que d’autres, il faut y mettre le prix. Par exemple, des permissions fines sont la plupart du temps une nécessité quand une entreprise décide de mettre sa documentation sur un wiki. C’est une fonctionnalité qu’on ne trouve généralement pas sur un wiki open source. Cependant vous pourriez être surpris d’apprendre à quel point les solutions wikis sont compétitives en termes de prix. Si les utilisateurs qui rédigent de la documentation technique profitent des avantages et des bénéfices offerts par une solution wiki, vous êtes capables de rationaliser l’intégralité de votre processus de documentation. Fini les coûts inutiles que vous subissiez par le passé, tout est désormais intégré dans une seule solution.

Alors, vous mesurez désormais la puissance d’une solution wiki ?!! Vous avez besoin de plus d’informations ? Ne vous inquiétez pas, nous n’en resterons pas là. Dans notre prochain billet nous vous expliquerons avec quelle simplicité il est possible de passer du brouillon à la publication de votre documentation…

Suite au prochain numéro !

bouton_atlassian_netapsys

Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Captcha *

Ce site utilise Akismet pour réduire les indésirables. En savoir plus sur comment les données de vos commentaires sont utilisées.