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 nicodache . Évalué à 3.
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 ;)
[^] # Re: on te l'a surement déja dit
Posté par G. R. (site web personnel) . Évalué à 1.
> qu'un roman auquel on pige rien
Comment une doc peut-elle être correcte si elle contient des fautes ?
# Quelques idées
Posté par galactikboulay . Évalué à 1.
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 Raphaël SurcouF (site web personnel) . Évalué à 2.
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.