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) ;-).
# Documentation
Posté par Raphaël SurcouF (site web personnel) . En réponse au message Besoin d'un conseil pour la rédaction de docs d'intégration technqiue et d'exploitation. É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(...)