Skip to content

La documentation

Nous avons souligné précédemment l’importance de la formalisation des méthodes de travail au sein d’un SI pour améliorer la qualité dans la fourniture de services informatiques. Dans ce cadre, la documentation occupe une place très importante dans le suivi et la traçabilité de nos différentes actions telles que la mise en place de nouveaux services, la gestion des configurations, les changements apportés au SI, la résolution des incidents et problèmes, l’aide aux utilisateurs, etc.

La réalisation d’une documentation et sa mise à disposition auprès du personnel et/ou des collègues ASR chargés d’intervenir sur les installations apparaissent donc comme des activités support importantes au sein de notre cartographie du SI. Il s’agit d’une bonne pratique permettant de retrouver l’information voulue au moment voulu, d’assurer la traçabilité des différentes interventions que nous sommes amenés à faire de manière à pouvoir fournir, si nécessaire, des explications détaillées à la direction, aux autorités compétentes sur la structure des installations et des services.

Un dépôt documentaire centralisé, riche et bien organisé fera gagner du temps aux ASR. Ces dépôts peuvent être placés par exemple sur un site web accessible et aisément modifiable par un système de gestion de contenu (Content Management System ou CMS) [9] ou encore un wiki [10].

Dans l’ensemble des tâches qui jalonnent le métier d’ASR, il est donc nécessaire de réserver du temps pour rédiger les diverses documentations nécessaires à la maintenance et à l’évolution du SI.

On distinguera deux grandes classes de documentation que l’on peut organiser dans deux dépôts distincts : celui destiné aux utilisateurs doit être accessible dans l’intranet de l’unité, alors que le second devrait être réservé aux ASR de par les informations confidentielles qu’il peut contenir.

1.1 La documentation pour les utilisateurs

Ce sont les documents qui permettent aux utilisateurs de comprendre les règles et procédures à suivre pour accéder et utiliser correctement les services qui sont mis en place par le service informatique. Cette documentation est très importante par le fait qu’elle peut rendre les utilisateurs autonomes en limitant l’appel systématique aux ASR.

A titre d’exemple, ce type de documentation peut être constitué de :

- un catalogue de service qui affiche les services fournis ainsi que les accords sur les modalités et
niveaux de service offerts par l’équipe informatique, les usages tolérés, les règles de conduite ;
- un livret d’accueil, établi par le service informatique, qui peut être remis aux nouveaux entrants et qui
peut constituer la base d’une description des services offerts aux utilisateurs. Ce livret peut alors
pointer vers des documentations plus complètes ou un catalogue de service ;
- les documentations d’utilisation de chaque service en production : par exemple 
    - comment utiliser le VPN du laboratoire, 
    - comment paramétrer le logiciel Thunderbird pour accéder à la messagerie, 
    - comment se connecter en ssh, 
    - comment paramétrer son PC pour accéder au service d’authentification des Universités (Eduroam...) ;
- les règlements (souvent rassemblés dans le règlement intérieur de l’unité de recherche) concernant
- l’utilisation des services, 
- la charte d’utilisation des moyens informatiques, ou encore 
- le document cadre relatif à la politique de sécurité de l’organisme considéré.
- etc.

1.2 La documentation technique destinée aux ASR

Cet ensemble de documents regroupe les informations techniques nécessaires pour que les ASR mettent en place et fassent fonctionner tel ou tel service. Ce sont les textes techniques propres au service informatique de l’unité et qui peuvent contenir des informations sensibles (plans du réseau, Access List de routeurs mises en place, noms et adresses internet de serveurs sensibles, mots de passe, etc.). La qualité de ces documentations doit permettre de confier ou déléguer l’exploitation de certains services à d’autres ASR de l’équipe ou chargés transitoirement d’intervenir.

Une procédure d’exploitation ou d’installation bien documentée est en effet plus facile à déléguer à d’autres ASR de l’équipe et peut faciliter l’intégration d’un stagiaire qui a alors à sa disposition un « mode d’emploi » clair et précis.

Ces documentations doivent donner une image de l’état technique des systèmes (services en exploitation à un temps donné), du réseau, des procédures pour assurer la continuité de service. Ces documentations sont mises à jour régulièrement, lors de chaque modification, pour être au plus près de la réalité.

En effet, comme on l’a vu précédemment dans la « gestion des changements », il est nécessaire pour les ASR d’enregistrer et de documenter les changements apportés dans l’exploitation du système d’information. Il s’agit davantage dans ce cas de constituer et de tenir à jour une « main courante » afin de tracer chronologiquement les changements de configuration apportés dans l’installation de tel ou tel logiciel, ou bien les causes et les résolutions d’incidents qui sont survenues dans le SI, ou encore l’historique des interventions et des mises à jour.

Comme exemple de ce type de documentation pour les ASR, on peut citer :

  • le plan à jour du réseau de l’unité, la configuration des commutateurs et des routeurs ;
  • l’inventaire des ressources informatiques ;
  • la documentation des configurations système indiquant comment un service a été installé et paramétré :
    • comment est configuré samba,
    • comment est assurée la redondance du serveur de mail au moyen d’heartbeat ou autres... ;
  • les procédures délicates que l’on fait rarement, par exemple, comment reconstruire le raid de la baie de disques ;
  • les procédures d’exploitation récurrentes que l’on veut pouvoir confier à d’autres membres de l’équipe informatique :
    • comment créer un compte ?,
    • comment changer les bandes de sauvegardes ?

Ces informations seront importantes en cas d’incidents ou de dysfonctionnements pour retrouver l’origine possible dans des interventions passées. A cet effet, notons que pour des raisons de disponibilité, il serait nécessaire d’assurer une redondance de cette documentation sensible sur support papier de manière à y avoir accès en cas de panne système

1.3 Comment réaliser ces documentations ?

Le but de ces documentations est qu’elles soient facilement accessibles, modifiables, partageables, correctement structurées, classées et en accès protégé.

L’ASR aura le choix du mode d’édition de ces documentations : documentation papier, fichier au format DocBook [11], site web ou wiki, etc.

Les dépôts documentaires de type wiki peuvent à cet effet procurer certains avantages :

  • leur accès est centralisé sur un serveur web, ce qui permet de ne pas avoir à chercher la documentation dans de nombreux fichiers et répertoires ;
  • leur simplicité d’utilisation facilite les mises à jour rapides de la documentation ;
  • ce type de documentation n’a jamais un caractère définitif. Il convient bien à un système en évolution permanente et on peut l’enrichir.

Ces dépôts de type wiki ont cependant aussi des inconvénients relatifs à la classification des informations et à leur structuration. Il est parfois difficile d’avoir une navigation claire dans un wiki, et la structuration peut être imparfaite ou mise à mal au fil des mises à jour de la documentation.

Quelle que soit la technologie du support de documentation choisie, il est en tout cas nécessaire de faire attention à assurer une diffusion restreinte des informations que l’on porte dans ce type de documentation du fait qu’elles touchent souvent à la sécurité des installations et de l’infrastructure.

Enfin, n’oublions pas qu’une édition papier de ces documentations est nécessaire en cas de problème système majeur qui empêcherait la consultation en ligne.