Comment documentez-vous votre travail, vos processus et votre environnement ?

Commentaire sur l'outillage.

Nous avons essayé les wikis en ligne, mais nous avons trouvé un certain nombre de limitations, qui peuvent être des goûts personnels, mais qui comprennent la structure du document et, plus important encore, la nécessité d'être connecté au serveur de documentation.

Le fait d'être connecté est un problème sérieux si vous êtes soit hors ligne, soit sur site (vous pouvez évidemment atténuer le problème sur site avec une connexion SSL sécurisée, etc.)

Notre processus de documentation actuel est le suivant :

• générateur de html statique
• syntaxe markdown
• système de versionnement distribué

Nous avons une mise en page "formelle" pour la documentation qui fournit la structure des menus (et le CSS associé pour le style visuel, etc.).

Générateur HTML statique

Nous utilisons un générateur html statique interne basé sur cubictemp et un certain nombre d'autres outils : pygments , docutils .

Les pages générées sont (pas ?) manifestement laides, car la plupart d'entre nous/nos administrateurs système/programmeurs savent ce qui est esthétiquement beau mais manquent totalement de coordination dans la construction de ce type de pages.

Mais il nous permet d'inclure des fichiers de configuration, des exemples de scripts, des pdf, etc., sans avoir à se soucier du formatage html ou de l'endroit où ils se trouvent sur le "serveur" pour être téléchargés.

S'il ne s'agit pas de HTML, il suffit de le déposer dans le dossier et d'y ajouter un lien url.

HTML fournit une structure "potentielle" pour la mise en page, et fournit également des "liens" entre les éléments de connaissance/contenu (ainsi que des mécanismes de structure de base, tels que la possibilité de créer des menus, des tables de contenu, etc. Avec HTML, chaque utilisateur peut maintenant faire fonctionner un petit serveur web sur sa machine, qu'il s'agisse de lighttpd ou de quelque chose de plus petit, ou simplement d'Apache ou d'IIS.

Toutes nos machines sont dotées de la puissance nécessaire à l'affichage html de base et fonctionnent suffisamment bien pour nous.

Syntaxe MARKDOWN.

Nous utilisons une version abâtardie de MARKDOWN, Textish et ou reStructuredTEXT pour laisser libre cours à notre créativité dans la rédaction de la documentation sans avoir à se préoccuper du langage HTML.

Cela signifie également que chacun peut utiliser son éditeur préféré (j'utilise Scintilla sous Windows et *Nix) tandis que les autres utilisent vi/vim.

Système de versionnement distribué.

Nous utilisons Git pour "distribuer" la documentation entre les utilisateurs. Oh, et nous utilisons également sa capacité de gestion des versions.

Le principal avantage pour nous est que nous pouvons tous travailler à la mise à jour de la documentation sans devoir être connectés au serveur et sans devoir publier des travaux "terminés". Nous pouvons tous travailler sur les mêmes parties de la documentation, ou sur des parties différentes, ou simplement consommer l'information.

Personnellement, je déteste être lié à un serveur pour mettre à jour des blogs, sans parler des wikis. Git fonctionne bien pour nous.

Commentaires sur le flux de travail

Les wikis semblent être à la mode pour la diffusion et la codification des connaissances, mais comme indiqué ailleurs, tous les processus deviennent difficiles à maintenir, et il faudra du temps pour trouver la combinaison d'outils qui répond le mieux aux besoins de vos équipes et qui est durable.

Les meilleures solutions finissent par être découvertes et non imposées.

Nous avons commencé à utiliser DokuWiki où je travaille.

Extrait du site web de Dokuwiki :

DokuWiki est un standard simple d'utilisation, principalement destiné à créer de la documentation de toute sorte. Il s'adresse Il s'adresse aux équipes de développeurs, groupes de travail et aux petites entreprises. Il possède une syntaxe simple mais puissante qui garantit que les fichiers de données restent lisibles en dehors du Wiki et facilite la la création de textes structurés. [ ] données sont stockées dans des fichiers texte - aucune base de données n'est nécessaire. aucune base de données n'est nécessaire.

J'ai trouvé que Dokuwiki était le plus facile à mettre en œuvre parce qu'il ne nécessite pas de base de données et qu'il était facile à configurer. Il y avait également des modules complémentaires qui permettaient d'utiliser ma base de données existante. Connexion aux comptes Active Directory Il dispose également du contrôle de version typique, où vous pouvez voir qui a posté quoi et où, et il a la capacité de revenir facilement à une version précédente si nécessaire. Il comprend également une page d'accueil personnalisable qui vous permet de changer facilement le type de contenu qui convient le mieux à votre environnement.

Doku Wiki ou Sharepoint pour d'autres éléments qui s'intègrent dans un graphique.

On s'habitue assez vite à poster sur un wiki et la syntaxe n'est pas si complexe. Il est très facile d'organiser l'information et de la rendre facile à retrouver plus tard par quelqu'un d'autre.

J'utilise visio pour créer des graphiques afin d'obtenir des explications plus claires (exportation en JPEG).

Nous utilisons un wiki. En fait, nous utilisons MediaWiki. En plus de MediaWiki, nous disposons de l'outil Extension sémantique de Mediawiki qui transforme notre MediaWiki en une sorte de base de données vaguement typée que nous pouvons interroger à l'aide de la catégorie, du titre, du contenu, etc.

Par exemple, supposons que je veuille voir tous les noms de réseau qui passent par le cluster F. Il me suffit d'utiliser la page Special:Ask pour interroger [[Category:cname]]. [[destination::cluster_f]] ... et toutes les pages classées dans la catégorie cname avec la destination cluster_f me seront renvoyées.

Nous soutenons quelques centaines de clients très disparates, et le fait d'avoir cette documentation dans un endroit central (et de l'avoir reliée de manière à ce que les cas particuliers restent documentés et liés à l'ensemble) est une chose extrêmement pratique. Il est évident que notre documentation doit être maintenue, mais vous pouvez adopter une approche plus "jardinière" de la maintenance parce que la boîte à outils mediawiki pour maintenir à jour un grand ensemble de données est déjà assez mature.

Avec les bons plugins, Trac peut devenir un système combiné de tickets et de wiki. Il est ainsi facile de créer des liens entre les tickets et les articles du wiki, et vice-versa.

Quelques plugins que j'aime bien :

• Plugin Tickets privés . Trac est conçu comme une base de données de bogues où tous les tickets et leurs réponses sont publics. Cela ne convient pas à un système de tickets informatiques, mais ce plugin corrige ce problème.
• Plugin Trac WYSIWYG . Soyons réalistes, la plupart des gens ne vont pas apprendre la wikisyntaxe pour vous faire plaisir. Cela leur donne un éditeur "ce que vous voyez est ce que vous obtenez" pour les tickets et les pages wiki.

Il y en a plusieurs plus pour Trac. Il n'est pas difficile de configurer et de personnaliser un système Trac à votre convenance !