Forum général.général Besoin d'un conseil pour la rédaction de docs d'intégration technqiue et d'exploitation

Posté par  .
Étiquettes : aucune
0
3
mar.
2005
Re-salut à tout le monde !

Merci pour vos réponse lors de mon dernier post sur ce même forum.
Pour rappel, je débute dans le vaste monde de l'administration système, et c'est devenu une véritable passion. Se lever le Lundi matin n'est plus un calvaire !
Bref...
Je fais de mon mieux coté technique afin d'assurer le meilleur taux de service possible, mais grosse claque lorsque je rédige des docs.
Bon déjà l'orthographe est l'un de mes points faible. Je viens d'acheter la série des Bescherelle.
Mais là où je plante vraiment c'est lorsque je dois documenter l'installation d'un serveur.
Exemple, je viens de finir d'installer une machine avec une FC3, et installer le serveur d'appli JonAS. J'installe un autre serveur sur lequel se trouve Postfix+MySQL+Cyrus Imap. Il a fallu que je recompile les sources de postfix pour rajouter le support mysql et déployé un max de bidouilles pour arriver au résultat final.
Donc tout fonctionne. Et l'instant d'angoisse me tombe dessus. La feuille blanche...
Je documente super mal mes actions. Je suis vraiment perdu dans ce process documentaire. Puis arrive la rédaction des docs d'exploitation et Pan!
Idem, ce que je fais, c'est nul.
Auriez vous un retour d'experience dessus ?

Merci d'avance.
Seb

  • # on te l'a surement déja dit

    Posté par  . Évalué à 3.

    mais documenter, c'est pas pour faire beau, c'est pour que toi dans 2 ans, ou un autre admin demain, puisse comprendre ce que tu as fait, pourquoi, comment, ou, etc...

    pas besoin de faire de la doc technique compréhensible pour tout le monde, la doc technique est utile uniquement aux "hommes de métier", et pour le reste de la doc...

    et puis, vaut mieux une doc correcte avec des fautes partout, qu'un roman auquel on pige rien ;)

  • # Quelques idées

    Posté par  . Évalué à 1.


    J'installe un autre serveur sur lequel se trouve Postfix+MySQL+Cyrus Imap. Il a fallu que je recompile les sources de postfix pour rajouter le support mysql et déployé un max de bidouilles pour arriver au résultat final.
    Donc tout fonctionne. Et l'instant d'angoisse me tombe dessus. La feuille blanche...


    Pourquoi ne pas tout simplement rédiger un document que tu vas découper en grandes étapes (ex: chapitre 1: compilation/installation de Postfix, chapitre 2: compilation/installation de MySQL, etc.) ?

    Ensuite dans chaque étape, tu indiques comment tu as effectué la compilation (options passées au ./configure, pré-requis pour pouvoir effectuer la compilation, etc.). Indique ensuite où tu as installé le produit, et comment tu l'as configuré (par ex en montrant les extraits pertinents des fichiers de configuration).

    Précise les embûches auxquelles tu as du faire face et comment tu les as résolues. C'est toujours bon de noter les subtilités de tel ou tel produit, à l'installation suivante, tu évites de galérer.

    Après comme quelqu'un l'a dit très justement, ce n'est pas un roman, donc qqch de clair et concis de quelques pages est bien plus utile qu'une doc de 50 pages.

  • # Documentation

    Posté par  (site web personnel) . Évalué à 2.

    Je ne sais pas comment ton entreprise gère la chose (si elle est certifiiée ISO-9002 par exemple) mais parfois tu as quelques règles à respecter: par exemple, ici, nous avons des modèles de documents conformes à la charte comportant des macros (Oui, c'est sous Word et oui, j'ai déjà essayé OpenOffice.org avec, les macros ne passent pas mais le modèle relativement bien à part les champs qu'elles sont censées remplir automatiquement et si quelqu'un savait comment porter des macros efficacement sous OOo, j'aimerais bien essayer).
    Le plus important à retenir est que la documentation, comme on te l'a fait déjà remarquer, est surtout destinée à pérenniser ton action. Non seulement pour toi mais aussi et surtout pour l'entreprise, donc tes collègues actuels ou futurs voire que tu ne connaîtras pas (sans parler des éventuels prestataires).
    Le premier conseil que je puis te donner serait de lancer un éditeur de texte (ou même de prendre un bloc-note) pour noter les commandes que tu réalises et les fichiers ainsi modifiés. N'hésite pas à tout noter, quitte à devoir par la suite, au cours de la rédaction de la doc, ne pas en retenir parce qu'elles seraient devenues inutiles, obsolètes, etc... Mieux vaut en avoir trop que pas assez. L'intérêt principal est de stocker immédiatement et rapidemment l'essentiel de ton travail (bien que ça puisse légèrement doubler ton temps de boulot). La plupart de ces notes te permettront tout de suite de situer le contexte dans lequel tu étais et de retrouver le cheminement de tes idées. L'autre conseil est procéder par étapes bien distinctes. Dans ton exemple, tu dois d'abord faire fonctionner postfix, puis cyrus-imapd, le couple des deux et enfin interviendra mysql. Pas moins de quatre étapes seraient donc nécessaires. Autant de chapitres pour le document final.

    Pour ce qui est du logiciel, je te conseillerais de les rédiger, si possible, sous OpenOffice.org. Pourquoi ? D'une part, il est libre et gratuit et ne nécessite pas de licence payante sur un nouveau poste, il est disponible sous Linux ET sous Windows, tu ne seras donc pas pénalisé même si tu changes d'environnement (à part si t'as un Mac ?). Outre le format propriétaire DOC, il est aussi capable de générer du PDF à la volée et, depuis l'arrivée de ooo2dbk[1], du DocBook !
    Et c'est ce dernier qui permettrait, à terme, d'archiver toute ta documentation, voire de l'indexer.

    Tout ceci est théorique, en pratique, à toi de t'adapter: par exemple, je rédige d'abord mes documents sous Word puisque j'ai une contrainte de norme ISO... Mais rien ne m'empêchera de les convertir via OOo par la suite (à part peut-être une microsofterie) ;-).

    [1]: http://linuxfr.org/2005/01/07/18017.html(...)

Suivre le flux des commentaires

Note : les commentaires appartiennent à celles et ceux qui les ont postés. Nous n’en sommes pas responsables.