Le blog de Genma
Vous êtes ici : Accueil » Informatique & Internet » Devenir SysAdmin d’une PME » Devenir SysAdmin d’une PME - La documentation

Devenir SysAdmin d’une PME - La documentation

D 22 octobre 2018     H 09:00     A Genma     C 1 messages   Logo Tipee

TAGS : Planet Libre Sysadmin Devenir SysAdmin d’une PME

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.

1 Messages

  • Personnellement, j’utilise un dokuwiki pour faire ma documentation... et j’ai un backup local du site au cas ou.
    Avec dokuwiki, on a :
    * le versionning
    * la gestion des utilisateurs
    * des mises à jours simple à mettre en oeuvre.
    * pas de base de donnée tout est en fichier plat
    * c’est du php.

    L’ennui de l’utilisation de gitlab et de savoir comment exploiter la doc hors de gitlab.
    Si on a une sauvegarde du wiki, les fichiers sauvegardé sont-il facilement exploitable et ou faut-il remonter un gitlab pour les utilisiser simplement ?

    Depuis un moment, je me demande si je ne devrais pas utiliser une techno comme mkdocs afin de générer un site statique. Ce serait moins piratable (accès uniquement en lecture) et plus performant (peu de php ou pas pour afficher une page). En n’oubliant pas de limiter l’accès par mot de passe.

    On peut toujours utiliser le système de gestion de version pour la sauvegarde.
    Et remonter une instance de la doc est très rapide.

    Je réalise ma doc à titre pro et personnel.
    Dans le cadre pro l’utilité est évidente.
    Dans le cadre perso, je l’utilise pour :
    * défini mon infra
    * l’automatisation des sauvegardes
    * la mise en place de la sécurité
    * ne pas perdre de temps a rechercher comment faire sur le web
    Quand on gère l’informatique de ses proches ce n’est pas négligeable de faire de la doc... (par exemple : j’ai fait comment pour installer cette imprimante sous debian ???)