Dans ce billet, je parlerai de documentation d'administrateur système, une documentation reposant sur du texte : les commandes shell (par exemple) restent du texte ; il n'y pas de schéma réseau ou autre (ou alors sous forme d'image intégrée). L'idée ici est de résumé un peu toute l'importance de la documentation, sujet souvent négligé par manque de temps, parce que l'on pense que c'est inutile etc.
Objectif premier de la document : Prévenir la perte d'information
Pour moi, l'objectif premier est de prévenir la perte d'information. J'évoquais dans mon billet Devenir SysAdmin d'une PME - Gestion du legacy- Billet n°1, l'héritage d'une infrastructure existante vieillissante, sur laquelle des générations d'administrateurs systèmes se sont succédés, et avec eux, la perte d'information.
En effet, la plupart du temps, la transmission de connaissances se fait (ou ne se fait pas) de façon orale au sein des membres de l'équipe Lorsque ces derniers partent vers d'autres horizons, même s'il y a eu une phase de passation de connaissances, il y aura toujours une perte d'information...
Toute modification et évolution doit donc être tracée dans la foulée et non "plus tard quand on aura le temps". Sinon, ce ne sera jamais fait et c'est le début d'un cercle vicieux et infernal, et le début de la fin de la documentation…
Et ce n'est pas le jour où l'on aura besoin d'une information qu'il faut se rendre compte qu'on ne la possède plus...
Documentation : définir un standard, une charte
Pour avoir une documentation de qualité uniforme, il faut définir des standards, une sorte de charte d'écriture de la documentation, des conventions. Un exemple valant mieux qu'un long discours, je vous renvoie vers la page Conventions pour le wiki Evolix que je trouve très bien. Ont été définies les règles de nommages, les conventions pour les commandes shell, les adresses réseaux etc.
Il faut également penser à avoir un sommaire, un chapitrage (chapitre et sous-chapitre), pour organiser la documentation de façon structurée.
Documentation, documentation, documentation
Il faut trouver un équilibre en ne rien documenter et trop documenter. Mais la documentation est à faire. Vaut mieux peu de documentation que pas de documentation du tout, mais vaut également mieux de la documentation utile que trop riche et inexploitable. Pour éviter d'aller trop dans le détail, on peut par exemple indiquer des prérequis, renvoyer vers des pages existantes pour avoir plus d'informations.
Il faut que la documentation se suffise à elle-même. Mais il ne faut pas réinventer la roue à chaque fois, et il ne faut pas hésiter à faire des renvois vers d'autres pages qui expliquent en détails, vers les documentations officielles. Les liens vers des sites extérieurs peuvent être mis en complément d'information mais le contenu doit rester disponible, car si le site est temporairement indisponible ou ferme de façon définitive, on perd l'information. Je conseillerai alors de recopier des bouts de tutoriaux existants, pour se les approprier, et avoir une uniformité dans la documentation.
Documenter pour les autres
Quand on écrit une documentation, il faut penser avant tout à l'écrire pour les autres. Ce qui nous semble évident ne l'est pas forcément pour quelqu'un d'autre, il ne faut pas faire de sous-entendu. Le choix des mots est important : ne pas hésiter à mettre plusieurs mots différents dans le titre, d'autant plus s'il y a un système de recherche par mot clefs.
Il faut que la personne qui lise la documentation ait un minimum de bagage technique et l'indication de prérequis : on ne va pas réexpliquer chaque commande Shell, donner un cours de Linux ou autre.
Il faut généraliser les explications, les commandes, sauf cas particulier : idéalement, une documentation sur un sujet donné doit être applicable à l'ensemble des serveurs de l'entreprise. On essaiera autant que possible de mettre des utilisateurs génériques, des IP par défaut etc. cf la charte de l'écriture de la documentation.
Les conseils :
faire relire la documentation écrite par quelqu'un d'autre ;
lui faire rejouer les commandes pour valider que tout marche bien.
Documenter, c'est bien. Maintenir à jour la documentation, c'est mieux
Documenter c'est bien mais sans maintenir la documentation à jour ça ne sert à rien. Là encore, il faut trouver un équilibre. Je conseille d'indiquer une date de dernière mise à jour des informations par exemple, pour pouvoir juger au premier coup d'œil de l'obsolescence potentielle de l'information.
On peut envisager une revue de documentation régulière, un passage en revue en se basant sur la date de dernière mise à jour pour vérifier si les informations sont toujours correctes, utiles. Normalement si la documentation est bien maintenue à jour au fil de l'eau, oui, il n'y a pas de pas obsolètes ou incorrectes. Mais comme on est parfois amené à travailler dans l'urgence, que tout le monde n'a pas la même rigueur etc. cette revue de documentation n'est pas inutile.
Documenter, mais avec quel outil ?
Sur ce point, je vous renvoie vers le billet que j'avais écrit Je vous renvoie vers mon billet Lifehacking - Gitlab, outil idéal ? et plus particulièrement sur la partie concernant le wiki. En quelques mots, je conseille de trouver un outil facile, pérenne dans le temps, qui sera facilement adopté par tous.
Les critères à prendre en compte sont :
multi-utilisateurs et possibilité d'éditer la documentation à plusieurs : le wiki Gitlab repose sur les utilisateurs Gitlab. On a un wiki par projet. On peut éditer à plusieurs, mais à tour de rôle.
accessible hors ligne : avoir un wiki en ligne (en mode web), c'est pratique car c'est centralisé. Mais le jour où on perd la connexion réseau et que les informations pour rétablir le réseau sont sur le wiki en ligne, on est bien embêté (c'est du vécu). L'avantage d'un wiki dans Gitlab est que l'on peut cloner le wiki en local et donc avoir la documentation en mode hors-ligne.
historisation : le wiki de Gitlab repose sur Git, on a donc bien l'historisation des pages et un suivi des modifications possibles.
liens entres les pages : des liens hypertextes pouvant être faits pour renvoyer vers les différentes pages du wiki en lui-même, vers des liens externes (dès lors que l'on a une url).
possibilité d'ajouter des images, des documents : il est possible d'intégrer des images directement dans le corps du texte dans le mode édition depuis le navigateur. Il est possible de faire un lien hypertexte vers un document ou un fichier qui est stocké dans un des dépôts d'un projet dans l'instance Gitlab.
un système de recherche : il faut pouvoir recherche à base de mots clefs pour retrouver les différentes pages abordant un sujet particulier.
Sauvegarde de la documentation
Comme toutes données, la documentation doit être intégrée à la politique de sauvegarde, il faut valider que l'on sait restaurer cette documentation etc...
Conclusion
Rien ne remplacera l'expérience acquise, mais on ne peut pas tout savoir et tout retenir. De ce fait, la documentation est importante. Dans ce billet je n'abordais que l'aspect documentation du point de vue de l'administrateur système, mais beaucoup des conseils et recommandations sont aussi valables pour d'autres métiers de l'informatique (développeur par exemple), et sont sûrement adaptables et généralisables à d'autres corps de métiers.
