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

Utilisez-vous un format wiki? Si oui, quel produit? (MediaWiki, Confluence, Sharepoint etc.)

Avez-vous créé une base de connaissances? (Documents courts axés sur le problème / la solution.)

Quels problèmes rencontrez-vous avec la création d'une documentation qui fonctionne, afin de ne pas recevoir l'appel lorsque vous êtes en vacances?

Pour moi, je constate qu’il ya souvent une certaine "inertie" organisationnelle impliquée dans l’obtention de la documentation. Il semble que ce soit un type de personne différent qui puisse effectuer une tâche, puis réfléchir à la façon dont elle l'a accomplie et la décrire de manière à ce que quelqu'un d'autre puisse le faire - un type de force pour vous "faites méta" et tout le monde n'est pas à l'aise pour le faire.

Mise à jour

Les réponses à ce jour incluent

• Confluence
• Flexwiki
• Fogbugz
• Mediawiki (avec des plugins tels que fckeditor)
• Sharepoint
• TWiki
• Docs Word / Excel / Visio
• Scripts documentés

Edit: Ne documentez-vous pas implicitement votre réseau avec votre système de surveillance? Nagios a toujours encouragé l'utilisation de la directive parents pour refléter la structure de votre réseau, et la directive notes_url est conçue pour vous permettre de vous connecter à un wiki ou à une autre documentation basée sur un navigateur. Donc, ici, la "documentation" est partagée entre le "document évolutif" du système de surveillance et une documentation plus détaillée et hors ligne sur un wiki. Puisque je passe beaucoup de temps à regarder Nagios, il est logique de s’efforcer de le rendre aussi informatif que possible.

Commentant l'outillage.

Nous avons essayé les wiki en ligne, mais nous avons trouvé un certain nombre de limitations, qui peuvent correspondre à des goûts personnels, mais incluent la structure du document et le fait le plus critique d'être connecté au serveur de documentation.

Être connecté est un problème sérieux si vous êtes hors ligne ou sur site (vous pouvez évidemment atténuer le site avec une connexion SSL sécurisée et autres.)

Notre processus de documentation actuel est:

• générateur html statique
• syntaxe de démarquage
• système de gestion de versions distribué

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

Générateur HTML statique

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

Les pages générées sont (pas?) Visiblement moche, car la plupart d’entre nous / nos administrateurs système / programmeurs savons ce qui est esthétiquement beau mais manquent totalement de coordination pour les construire.

Mais cela nous permet d'inclure des fichiers de configuration, des exemples de scripts, des fichiers PDF, etc. sans avoir à vous soucier du formatage HTML, ni à savoir où le trouver sur le "serveur" pour le téléchargement.

Si ce n'est pas du HTML, déposez-le simplement dans le dossier et ajoutez-y un lien URL.

Le HTML fournit une structure "potentielle" pour la mise en page, ainsi qu'un "lien" critique entre les éléments de connaissance / de contenu (ainsi que les mécanismes de structure de base, tels que la possibilité de créer des menus, des tableaux de contenu, etc.). Avec HTML, chaque utilisateur peut maintenant exécuter un petit serveur Web sur leur machine, que ce soit lighttpd ou quelque chose de petit ou tout simplement aller à fond avec Apache ou IIS.

Toutes nos machines ont le béguin pour le service html de base et fonctionnent assez bien pour nous.

MARKDOWN syntaxe.

Nous utilisons une version bâtarde de MARKDOWN, Textish et / ou reStructuredTEXT pour permettre à notre créativité de créer de la documentation sans avoir à se soucier de HTML.

Cela signifie également que tout le monde utilise son éditeur préféré (j'utilise Scintilla sous Windows et * Nix), tandis que les autres utilisateurs utilisent vi / vim.

Système de versioning distribué.

Nous utilisons Git pour "distribuer" la documentation entre 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 être connecté au serveur et sans avoir à publier des travaux "terminés". Nous pouvons tous travailler sur les mêmes parties de la documentation, sur différentes parties ou simplement utiliser les informations.

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

Commenter le workflow

Les wiki semblent être la "mode" de diffusion / 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 votre équipe et qui est durable.

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

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

Sur le site Web de Dokuwiki:

DokuWiki est un Wiki conforme aux normes, simple à utiliser, visant principalement à créer de la documentation de tout type. Il est destiné aux équipes de développement, aux groupes de travail et aux petites entreprises. Il a une syntaxe simple mais puissante qui garantit que les fichiers de données restent lisibles en dehors du wiki et facilite la création de textes structurés. Toutes les données sont stockées dans des fichiers de texte brut - aucune base de données n’est requise.

J'ai trouvé Dokuwiki le plus facile à mettre en œuvre car il ne nécessite aucune base de données et il était facile à configurer. Il y avait aussi des modules complémentaires qui permettaient d'utiliser les ouvertures de session de mes comptes Active Directory existants plutôt que d'avoir à créer des comptes pour tout le monde, ce qui était un avantage considérable par rapport à la plupart des autres systèmes wiki que j'ai trouvés. il possède également le contrôle de gestion de version typique, qui permet de savoir qui a posté quoi et où, et il est également possible de revenir à une version précédente facilement si nécessaire. Ils incluent également une page d’accueil personnalisable sur laquelle vous pouvez facilement changer le type de contenu qui convient le mieux à votre environnement.

Doku Wiki ou Sharepoint pour d’autres choses qui s’intègrent dans un graphique.

Vous vous habituez assez vite à publier sur un wiki et la syntaxe n’est pas vraiment complexe. Il est très facile d'organiser des informations et de les retrouver plus tard par quelqu'un d'autre.

J'utilise Visio pour faire des graphiques pour des explications plus claires (export au format JPEG).

Nous utilisons un wiki. En fait, nous utilisons MediaWiki. En plus de MediaWiki, nous avons l’ extension Semantic Mediawiki installée, qui transforme en fait notre MediaWiki en une sorte de base de données faiblement typée que nous pouvons interroger avec la catégorie, le titre, le contenu, etc.

Par exemple, supposons que je veuille voir tous les noms de réseau qui acheminent vers le cluster F. Il suffit d’utiliser la page Special: Ask pour interroger [[Category: cname]] [[destination :: cluster_f]] .. .. et il renverra toutes les pages classées en tant que cname avec la destination en tant que cluster_f.

Nous prenons en charge quelques centaines de clients très disparates. Il est donc extrêmement utile de disposer de cette documentation dans un lieu central (et de la relier de manière à ce que les cas particuliers restent documentés et liés dans l’ensemble). De toute évidence, notre documentation doit être maintenue, mais vous pouvez adopter une approche plus "jardinière", car la boîte à outils mediawiki permettant de conserver un grand ensemble de données à jour est déjà bien mature.

Avec les bons plugins, Trac peut devenir une combinaison de ticket et de système wiki. Cela facilite la liaison de vos billets vers des articles de wiki et inversement.

Quelques plugins que j'aime bien:

• Tickets privés . Trac est construit comme une base de bogues où tous les tickets et leurs réponses sont publics. Ce n'est pas approprié pour un système de ticket informatique, mais ce plugin résout ce problème.
• Trac WYSIWYG plugin . Regardons les choses en face, la plupart des gens ne vont pas apprendre wikisyntax pour vous rendre heureux. Cela leur donne un éditeur "Ce que vous voyez est ce que vous obtenez" pour les tickets et les pages wiki.

Il existe plusieurs autres personnalisations pour Trac. Il n'est pas difficile d'installer et de personnaliser un système Trac à votre goût!

Dans mon travail précédent, j'ai utilisé Twiki. Cela a assez bien fonctionné.

A côté de cela, j'ai tendance à automatiser la plupart des tâches et à documenter les scripts (pas toujours avec beaucoup d'enthousiasme, mais quand même ...). Il est facile de documenter les scripts lors de leur conception, donc pas de véritable surcharge ...

La combinaison des deux (et l'utilisation du contrôle de version pour les scripts) a assez bien fonctionné.

Un mélange de documents JIRA, Confluence et Word.

Institutionnaliser le savoir

Nous avons commencé avec des documents. Ensuite, nous en avons stocké certaines dans des bibliothèques Sharepoint. Puis récemment nous sommes passés au wiki Sharepoint. J'aime l'approche sans frictions du wiki pour la mise à jour rapide des éléments, même si les wikis de Sharepoint laissent à désirer en matière de support graphique et de formatage pour des éléments tels que les tableaux. C'est bien pour le texte et l'éditeur intégré permet un formatage HTML de base et des listes ordonnées / non ordonnées. Il existe d'autres alternatives peu coûteuses à Sharepoint.

Nous disposons également d’une sorte de base de connaissances informelle pour nos tickets d’assistance dans notre logiciel d’assistance, Track-It de Numara. Ce n'est pas parfait mais ça marche.

Faire en sorte que le personnel utilise les connaissances institutionnalisées

Je suis d’accord avec votre évaluation selon laquelle l’institutionnalisation des connaissances ne représente qu’une partie de la bataille. Si votre organisation et vos employés ne sont pas habitués à "effectuer des recherches en premier lieu, demandez ensuite", vous constaterez que l'ancienne méthode prévaut: tout le monde cherchera toujours des réponses auprès des gourous formels et informels, et il sera toujours plus facile de demander aux gourous formels. la personne à côté de vous que de chercher par vous-même.

Faire face à cela impliquera une certaine gestion du changement; comme la plupart des initiatives de changement réussies qui touchent plus qu'une petite équipe, il sera utile d'obtenir l'appui et le soutien de la direction. Vous devez vraiment forger un nouveau comportement dans deux directions; quelqu'un doit capturer les connaissances et les gens doivent les utiliser. Ce qui est encore plus dur, c’est que les gens doivent également tenir ces données à jour.

Quelques idées: il faudra probablement des encouragements sous la forme d’une politique formelle stipulant que les tickets résolus et les problèmes doivent être documentés dans la base de connaissances ou le wiki avant de pouvoir être considérés comme clos. De plus, les leaders du savoir qui se font poser des questions ne doivent pas toujours offrir des réponses sur demande; ils ont besoin de diriger les gens vers les wikis et de les habituer à les vérifier en premier. Une autre chose à faire serait de mettre les données à la disposition des utilisateurs pour qu'ils puissent se prendre en main, afin que le problème puisse éventuellement être résolu avant qu'il ne devienne un autre élément que le personnel technique doit jongler.

Ce qui serait bien, c'est que notre système d'assistance ait un système similaire à StackOverflow et ServerFault: lors de la saisie d'une question, le moteur de recherche trouve des éléments similaires et les propose, afin que les utilisateurs puissent les consulter avant même de soumettre la question.

Dans mes deux derniers lieux de travail, j’utilisais le wiki de Sharepoint, à côté d’une bibliothèque de documents contenant certains documents (tels que les plans de re-développement et les plans de mise à niveau ponctuels) qui ne pouvaient pas être facilement créés en tant que documents wiki. Ces documents avaient des liens depuis le Wiki. Le wiki présente de nombreux avantages dans ce domaine, car de nombreuses personnes peuvent le modifier, le versionnage est intégré, facile à rechercher et accessible, etc. Pour rédiger rapidement des notes ou des idées, j’utiliserais OneNote ou un tableau blanc.

J'avais déjà créé des bases de connaissances, sous forme de forum (à la fois dans Lotus Notes et MS Sharepoint), mais je dois dire que rarement, les gens consultent ces bases pour voir si un problème avait déjà été résolu. Une telle solution doit venir du premier jour avec un moteur de recherche très puissant et efficace.

Si vous souhaitez créer des documents pouvant être utilisés pendant les vacances, écrivez-les comme si vous essayiez d'instruire l'un de vos parents. Ce n'est pas à 100% infaillible, mais aide parfois. Cela dépend de qui le lit.

Sharepoint est sympa.

Ses fonctions de recherche permettent d’indexer presque tous les types de documents, ce qui facilite grandement la recherche de documentation.

Il peut également créer des modèles, ce qui peut faciliter la tâche si, par exemple, vous avez une fiche d’information standard pour chaque serveur que vous créez.

Il peut également créer une version de vos documents afin que vous disposiez d'un historique d'audit des modifications apportées à la documentation.

De plus, les fichiers contenus dans les bibliothèques de documents sont accessibles sur le Web, dans Outlook ou via un partage UN-out de la boîte.

Nous utilisons MediaWiki (avec fckeditor) depuis plusieurs années, bien que je dois dire que ce serait bien si la manipulation des images (c'est-à-dire des captures d'écran) était plus facile. Et même s'il est essentiel de pouvoir effectuer des recherches, je trouve que les pages de MediaWiki manquent souvent. Peut-être que c'est juste une question d'apprendre à mieux chercher (ce qui va à l'encontre du but de permettre aux autres de faire votre travail de manière simple)

À l'heure actuelle, nous discutons de tout transférer sur MS Sharepoint , mais pas nécessairement sur leur wiki. Je pense que Sharepoint est capable de faire une recherche documentaire complète d' une manière qui annule certains des avantages d'un wiki, alors nous verrons où cela va.

(pas hâte au processus de portage de toute notre documentation actuelle cependant :))

Nous utilisons un wiki. Certes, la syntaxe a pris un peu pour s'y habituer, mais celui que nous utilisons (twiki) stocke ses données entièrement sous forme de fichiers texte. Cela nous permet de les lire facilement en cas de sinistre, car nous pouvons les restaurer n'importe où, et les rechercher à partir de la ligne de commande via grep, puis les lire dans l'éditeur de texte de notre choix.

Chaque serveur a une page, avec une collection standard de sous-pages pour les informations de gestion des modifications, les notes de démarrage / arrêt et de configuration, ainsi que les informations DNS, pare-feu et des ressources.

Nous nous apprêtons à passer à une version d’un service Sharepoint pour essayer de nous débarrasser d’un mélange de documents Word répartis sur trois serveurs et savoir qui est le nombre de dossiers. Actuellement, nous avons un énorme tableur Excel contenant des hyperliens vers les documents qui y sont décrits.

Ce n’était pas la meilleure façon de le faire, mais lorsque la société a démarré, elle n’avait jamais prévu la gestion de la documentation interne et laissait à chaque groupe le soin de décider comment trier et stocker sa propre documentation à sa guise. Nous essayons maintenant de fusionner dans un système unifié, qui sera basé sur l’une des offres Sharepoint.

Dans l’ONG où je travaille, nous utilisons simplement des fichiers texte placés dans un dossier pour les procédures critiques. Personnellement, en tant qu'administrateur système / développeur Web hybride, j'utilise une base de connaissances de fichiers texte dispersés dans un répertoire d'arborescence. C'est mon Memex et je note presque tout ce qu'il contient (personnel, travail, etc.). Ce schéma est très facile à utiliser avec Jedit, un véritable couteau suisse pour le traitement de texte. J'ai trouvé son plug-in de plan, son pliage de code et ses fonctionnalités d'hypersearch également indispensables. Tout cela sauvegardé en toute sécurité par rsync sur un serveur distant accessible par ssh.

Ajoutez à cela le MakeLink Firefox Extension et vous avez le gestionnaire de favoris parfait.

Nous utilisons flexwiki , qui est un dotnet et open source.

Euh ... que diriez-vous de Fogbugz? :)

Nous utilisons ScrewTurn pour le contenu et SharePoint pour stocker des documents / images.

Il y a des choses intéressantes ici - j'aime celle sur les mots de passe dans un coffre-fort.

Nous utilisons une combinaison de fichiers texte pour une recherche rapide avec grep. Et SharePoint pour une collection plus organisée de documentation détaillée (diagrammes Visio, etc.).

En tant que clients Google Apps (Entreprise), nous utilisons totalement les sites de Google Sites: leur "saveur" de wiki. Facile à utiliser et nous avons été très bien adoptés par les administrateurs et les développeurs.

Je n'ai pas vu cette question avant de répondre à une autre question , mais on y va.

Nous utilisons plusieurs outils et méthodes.

• Spécifications fonctionnelles des composants et des logiciels d'infrastructure.
• Deux Wikis Confluence . Un pour la documentation interne de l'entreprise (stratégies, procédures, infrastructure interne et informatique, etc.) et un pour nos produits logiciels open source.
• Tests RSpec et Cucumber . Notre logiciel est principalement écrit en Ruby et nous pratiquons BDD / TDD . Par conséquent, les tests de spécification pilotent le code réel et la documentation.
• Documentation de code en ligne. Nous utilisons le balisage RDoc dans les commentaires de code.
• Gestion de configuration déclarative ( Chef ). Tous nos serveurs sont gérés avec Chef, qui "s'auto-documente" au moyen de ressources documentaires dans des recettes et des livres de recettes.

Nous aimons Confluence parce qu’il est très flexible et puissant, complet et complet, et qu’il est lié au logiciel de gestion de tickets que nous aimons, Jira .

Dans les entreprises précédentes, j'ai utilisé une variété d'outils et de méthodes et beaucoup ont essayé de rester avec une seule ressource fourre-tout (comme un wiki) pour tout. Le problème avec cela est de documenter divers sujets avec un seul outil qui ne convient pas uniquement pour couvrir ce sujet signifie que beaucoup de choses ne seront pas documentées du tout, car il est difficile de migrer les informations. En tant que geek Unix / Linux, je crois que chaque tâche nécessite un outil spécifique, et que cet outil devrait parfaitement convenir à cette tâche.

Cette question est très bien une copie de celle-ci et j'ai déplacé ma réponse là-bas.

Je fais la plupart de la documentation pour mon entreprise et le format qui a été établi lorsque j'ai commencé à travailler ici était MS Word pour les originaux modifiables, exporté au format PDF pour les versions générales en lecture seule. Cela fonctionne assez bien pour les projets où une seule personne met à jour le document et, puisque cette personne est généralement moi, la direction n'a pas jugé nécessaire de changer.

Nous avons commencé à documenter nos bogues et les tâches à venir avec Trac , tout en utilisant une extension "Peer Review" pour les révisions de code. Notre équipe a été très bien accueillie car il est simple de collaborer et de naviguer facilement. Quelques autres membres de l'équipe ont exprimé le souhait de commencer à collaborer davantage avec les spécifications, les procédures de test et les manuels. Nous examinons donc DocBook / XML exporté au format PDF pour la documentation publique, comme les manuels, et les pages Trac WIKI pour les documents internes, tels que les spécifications et le logiciel. les procédures d'essai.

Dans mon esprit, les plus gros problèmes lors du choix d'un format de documentation sont les suivants:

1. Est-ce facile à créer?
2. Est-ce facile à entretenir?
3. Est-il facile à maintenir si quelqu'un d'autre l'a écrit?
4. Peut-il être exporté / converti dans d'autres formats sans trop de soucis?

1 à 3 me facilitent la vie et sont importants pour produire une documentation rapidement sans devenir fou. Je pense que le quatrième est le plus important pour le client, car les formats vont continuellement changer. Le format Microsoft Word 2003 ne sera pas disponible pour toujours, pas plus que notre implémentation actuelle de PDF. Je dois m'assurer que tous nos clients peuvent lire nos documents, quel que soit leur système d'exploitation ou leur lecteur de choix.

Nous utilisons MediaWiki avec différents plugins, y compris SemanticMediaWiki. SMW est bien, car il transforme notre installation MediaWiki en une grande base de données relationnelle de forme libre pouvant être interrogée à volonté. Besoin de savoir sur quel serveur se trouve un site Web? Visitez sa page. Besoin de savoir quels sites Web sont hébergés sur un serveur? Exécuter une requête, et il va choisir les noms de page en fonction de la balise appropriée sur la page de chaque site Web.

Je ne répondrai pas avec un système de documentation que j'ai utilisé, mais avec quelque chose que j'ai vu utilisé et que je trouve très bon: http://stackexchange.com/

stackexchange est la plate-forme de questions-réponses qui s'exécute sous serverfault (enfin, techniquement, ce n'est pas exactement la même chose, mais pour notre propos, nous pouvons supposer que c'est la même chose).

Fogbugz l' utilise .

Il y a un article de blog intéressant d'un employé de Fogbugz où j'ai trouvé ces citations:

À toutes fins utiles en dehors des spécifications de produit, je pense que les formes de discussion et de wiki d'entreprise ont été durement touchées.

...

Depuis que nous utilisons FogBugz.StackExchange.com comme plate-forme d'assistance, je n'ai jamais répondu à la même question deux fois. Nous avons même un serveur SE interne que nous utilisons pour les questions-réponses non publiques, et les mêmes principes s'appliquent ici.

Ils utilisent stackexchange pour la base de connaissances et la base de connaissances internes destinées aux clients.

Je suis intéressé de voir si de telles plateformes de questions-réponses sur l'échange de connaissances remplaceront les wiki d'entreprise.

Chez mon précédent employeur, j’utilisais des fichiers Word, Excel et Visio rassemblés dans un dossier. Une copie papier de tout était conservée dans un classeur dans mon bureau. J'étais le seul informaticien, il était donc inutile que quiconque ait accès à ces informations.

Chez mon employeur actuel, nous utilisons Macola ES de Exact Software, mais je préfère quand même écrire ma documentation dans Word et la télécharger dans Macola en tant que pièce jointe à l’aide de l’éditeur de document intégré.

Sur mon lieu de travail, j'ai déposé ScrewTurn Wiki sur l'un de nos serveurs de développement Windows et l'ai connecté à notre serveur SQL. Cela fonctionne vraiment bien, fonctionne rapidement et reste principalement hors de notre chemin pour la documentation. Au cours des deux semaines qui ont suivi son déploiement, nous avons déjà ajouté environ 60 pages d'informations, destinées uniquement à notre équipe (~ 10 personnes).

Jusqu'à présent, nous conservons des informations sur les projets actuels et passés, et nous avons commencé à ajouter des informations sur les applications, telles que la façon de les construire à partir de zéro, des URL et d'autres informations importantes pour les nouveaux développeurs de l'équipe.

Une de mes pages préférées sur le wiki a été la page des outils et des bibliothèques. Nous y avons commencé à ajouter des informations sur nos outils de productivité préférés et les bibliothèques que nous utilisons beaucoup, comme par exemple grepWin pour la recherche de texte dans Windows.

Je recommanderais vivement de consulter la gamme complète de wiki disponibles et de trouver celui qui convient à votre utilisation, fonctionnalité et environnement de déploiement prévus. J'ai choisi ScrewTurn parce qu'il est facile à utiliser et que nous avions beaucoup de place sur notre serveur WinServer local, mais YMMV.

Nous utilisons Confluence comme wiki et point de partage pour les documents dans certains cas. Je crois que le format wiki en ligne est un choix préféré lorsque vous avez besoin de partager ces informations très largement et ce qui est beaucoup plus important lorsque des documents vont être édités et mis à jour très souvent. Donc, je pense que les articles de la base de connaissances sont mieux à mettre dans wiki.

Nous transférons actuellement nos informations provenant de divers documents répartis sur le réseau vers deux emplacements:

1. Un wiki disponible sur notre intranet
2. Une copie des informations relatives à un serveur particulier dans ce répertoire serveurs / racine.

Pour les diagrammes de réseau, Bloc-notes réseau .

En outre, lors de l’enregistrement du quoi, souvenez-vous d’enregistrer pourquoi quelque chose est configuré ainsi. Cela aide à éviter que des idées qui semblent être une bonne idée ne se transforment en erreurs.

Nous avons constaté que MediaWiki avait démarré lentement, mais une fois que des personnes extérieures au service informatique avaient eu vent de la facilité avec laquelle il était facile d'ajouter des commentaires, des modifications, des modifications, etc., cela devenait indispensable. Les développeurs l'utilisent pour la documentation interne, le service des installations. pour poster des avis, etc. Il est devenu un outil de documentation informatique.