Premiers pas avec la documentation

Nous n'avons fait aucune documentation sur mon lieu de travail. Je suis complètement nouveau et demande des conseils pour commencer.

J'ai quelques questions:

• Quels sont les documents essentiels qu'un administrateur système doit écrire et conserver? Et pourquoi sont-ils si importants?

• Comment synchronisez-vous votre documentation avec le système? Comment minimisez-vous la duplication des informations?

• Guides recommandés, meilleures pratiques, anti-modèles?

depuis 2003, je documente tout dans notre wiki interne.

Les serveurs

• spécifications matérielles
• informations de garantie
• informations sur le réseau
• et bien sûr le logiciel et la configuration installés

Workflows

par exemple, comment ajouter ou supprimer un utilisateur et lui donner accès à tous les services pertinents

Liens importants

• lien vers toutes vos interfaces web
• lien vers les URL de surveillance (nagios, munin, apc-monitoring ...)
• lien vers le wiki (pour la version imprimée!)

Instructions d'urgence

que faire si le serveur intranet / internet / serveur web / etc est en panne

Important:

Choisissez un moteur wiki avec une exportation facile au format PDF!
Ce n'est pas utile si vous êtes en vacances, le serveur exécutant votre wiki est en panne et personne ne sait quoi faire car votre documentation est hors ligne

Jetez un œil à twiki, docuwiki ou mediawiki.

BTW:

il existe un plugin OpenOffice.org pour écrire directement sur mediawiki - très pratique.

ÉDITER:

C'est aussi agréable d'écrire quelques infos /home/adminuser/maintenance. Cela se fait rapidement et peut être très utile si plusieurs administrateurs travaillent sur un serveur. par exemple:

2009-06-27 -thorsten-
          running aptitude update && aptitude full-upgrade
          everything seems ok
2009-06-25 -andreas-
          cups-pdf wasn't reachable. restarted cups
2009-06-23 -thorsten-
          deleted old log under /var/log/squid
etc.

Alors que vous vous rendez compte que si tout le monde veut (et a besoin) de documentation, vous devez également reconnaître que personne n'a le temps de lire et d'étudier les choses.

Donc, n'écrivez pas la documentation qui doit être étudiée - au lieu de cela, structurez votre documentation de manière à permettre à quelqu'un de trouver rapidement les informations dont il a besoin, quand il en a besoin - ce qui pourrait bien être pendant que le système est en panne et que le CTO est respirer dans son cou.

Dans cet esprit, quelques suggestions ...

• Évitez les gros blocs de texte
• Les listes à puces sont votre ami
• Un diagramme clair est doré
• La répétition est une bonne idée (1)
• Facilitez la mise à jour et l'extension

(1) Ne créez pas une seule source de vérité et ne forcez pas les gens à la traquer. Plus l'idée est importante, plus vous devez la répéter.

Documents essentiels:

• Documentation du serveur - spécifications / dispositions du disque / logiciel installé / tout ce qui est important
• Procédures courantes - tout ce qui est fait qui n'est pas «trivial» devrait avoir une procédure documentée, surtout si c'est quelque chose qui n'a pas été fait auparavant.

Garder la documentation synchronisée peut être à peu près une affaire de «correction comme vous voyez des erreurs». Parallèlement à cela, il faut prendre conscience que la documentation peut et sera obsolète et qu'elle ne doit pas être suivie aveuglément sans en tenir compte. La documentation est là pour aider un administrateur dans ses tâches, et non pour être un ensemble pas à pas de règles qui remplacent la pensée critique.

Minimiser la duplication - l'utilisation de quelque chose comme des wikis où vous pouvez lier la documentation peut vous aider, au lieu de répéter des informations, il vous suffit de créer un lien vers celle-ci. Le problème est que la personne qui rédige la documentation doit savoir que les informations qu'elle est sur le point de dupliquer existent déjà. C'est généralement une question de bonne organisation.

J'ai trouvé que la création d'un modèle est d'une grande aide. Dans mon cas, c'est un modèle Word, mais utilisez les suites qui vous conviennent. Créez un fichier squelette, complet avec le champ de la table des matières et les sections comme vous le souhaitez. Une fois que vous l'avez utilisé plusieurs fois et que vous avez effectué des réglages fins, vous allez créer de nouveaux documents beaucoup plus rapidement. La cohérence du format sera d'une grande aide, tant pour la création de documents que pour une utilisation ultérieure. La documentation doit être stockée dans un emplacement logique et dans une structure de répertoires logiques.

Je suis personnellement opposé à la répétition pour le simple fait qu'elle rend l'entretien inutilement difficile et prend du temps. Plutôt que de dupliquer des documents ou des parties de documents, créez des références à d'autres documents, le cas échéant. Si quelque chose change, vous ne devriez jamais avoir à modifier la documentation pertinente plus d'une fois ou à plusieurs endroits, sinon vous aurez une collection de documents en conflit, ce qui n'aidera personne.

Lors de la création de votre documentation, gardez à l'esprit à quoi elle sert. Quelqu'un à un moment ultérieur devra l'utiliser. Sera-t-il utilisable pour faire le travail sans connaissance préalable?

Pas une réponse directe à votre question, mais un pointeur dans la bonne direction:

J'ai trouvé la pratique de l'administration du système et du réseau , par Limoncelli et Hogan (alias la Bible Sysadmin) très utile car il s'agit de questions de "meilleures pratiques", telles que la documentation. Si vous ne le savez pas déjà, assurez-vous d'enquêter chaque fois que vous en avez l'occasion.

Pour moi, le plus important est de le rendre facile à utiliser. S'il est difficile d'orchestrer, les gens l'éviteront. J'ai choisi le wiki de Trac comme support pour notre documentation pour ces raisons:

• Situé au centre.

  Plus d'une copie active d'un même document prête à confusion. Si vous êtes en mesure de renvoyer tout le monde au même endroit, à la fois les contributeurs et le public, vous pouvez simplifier le processus.

• Édition et formatage simples.

  Tant de temps est gaspillé sur de jolis modèles Word et conforme au style du dernier auteur. Si vous n'embourbez pas les gens avec cela, il est plus facile de les modifier en déplacement et les contributeurs sont plus enclins à le faire. Séparez les éléments autant que vous le souhaitez avec TracLinks.

• Historique d'audit.

  Il est important de savoir qui a fait quoi, quand et pourquoi. Si vous pouvez l'associer à des tickets de demande de changement et à des journaux de validation de configuration, c'est encore mieux. Les crochets de validation SVN sont parfaits pour cela.