Premiers pas avec la documentation


21

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?


Réponses:


15

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.

2
+1 pour le conseil de secours si le wiki est en panne.
Manuel Faux

Qu'est-ce que OOo? On dirait OpenOffice, mais je n'arrive pas à comprendre le dernier "o". Si vous pouviez nommer le plugin, ce serait génial.
Daniel C.Sobral

3
à droite, OOo est OpenOffice.org ;-) L'extension: extensions.services.openoffice.org/de/project/wikipublisher
ThorstenS

13

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.


2
Cependant, avec plusieurs sources de documentation, plusieurs emplacements doivent être mis à jour s'ils deviennent obsolètes et doivent être modifiés. Un bon moyen de contourner cela (si vous avez un wiki ou quelque chose de similaire) est d'essayer de créer une véritable source de vérité et de la relier à autant d'endroits que nécessaire.
Mark

Dans une certaine mesure, je suis d'accord - les liens et les références croisées peuvent être très utiles. Il existe cependant un compromis - dans la conception de la base de données, il est courant de dénormaliser les tableaux pour faciliter les rapports. Je pense que la même approche est pertinente ici - pour faciliter la consommation de la documentation, la répétition des faits clés peut être utile.
Bevan

il est acceptable de diffuser largement les principes, mais pour des choses comme les adresses IP, les mots de passe, la gestion de la configuration, une source unique et centralisée de données faisant autorité, avec des sauvegardes adéquates, est la clé d'une administration saine.
Tom H

Je suis d'accord - tant qu'elle est à la fois bien connue et facilement accessible - une seule source secrète faisant autorité est un contre-modèle trop courant.
Bevan

Je suis en désaccord avec véhémence sur la répétition, car l'un sera mis à jour, mais pas d'autres. Ou ils seront mis à jour de manière incohérente. Au lieu de cela, les documents les plus importants devraient être plus facilement liés .
gWaldo

5

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.


4

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?


3

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.


La 2e édition de ce livre contient un chapitre sur la documentation. Un livre connexe, «Gestion du temps pour les administrateurs système», contient un chapitre sur la documentation qui met davantage l'accent sur ce que vous devez faire plutôt que sur ce que votre organisation doit faire.
TomOnTime

0

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.


J'utilise également trac pour la documentation d'un projet. Ce qui manque vraiment, c'est une sorte de fil d'Ariane dans le wiki. J'espère que cela arrive bientôt.
ThorstenS
En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.