Comment documez-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 de problème/orienté solution.)
Quels défis trouvez-vous avec la création de documentation qui fonctionne, de sorte que vous ne recevez pas l'appel lorsque vous êtes en vacances?
Pour moi, je trouve qu'il y a souvent une certaine quantité d'organisation "inertie" impliquée dans la réalisation de la documentation. Il semble être un type différent de personne qui peut faire une tâche, alors réfléchir comment Ils ont fait la tâche et la décrivent ainsi que quelqu'un d'autre peut le faire - genre de forces à vous "aller méta" et Tout le monde n'est pas à l'aise de faire ça.
Mettre à jour
Les réponses jusqu'à présent incluent
- Confluence
- Flexwiki
- Fantaisie
- MediaWiki (avec des plugins tels que fckeditor)
- SharePoint
- Twiki
- Word/Excel/Visio Docs
- Scripts documentés
Éditer: Vous 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 créer un lien vers une documentation Wiki ou une autre de navigation. . Voici donc que la "documentation" est divisée entre le "document de vie" du système de surveillance et une documentation hors ligne plus détaillée dans un wiki. Depuis que je passe beaucoup de temps à regarder Nagios, il est logique de mettre des efforts pour le rendre aussi informatif que possible.
Nous avons commencé à utiliser dokuwiki où je travaille.
Du site Web de Dokuwiki:
Dokuwiki est une conformité de normes, simple à utiliser Wiki, principalement destinée à créer une documentation de tout type. Il est ciblé des équipes de développeurs, des groupes de travail et de petites entreprises. Il possède une syntaxe simple mais puissante qui veille à ce que les datafiles restent lisibles en dehors du wiki et facilitent la création de textes structurés. Toutes les données sont stockées dans des fichiers texte simples - 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 de configurer. Il y avait également des modules de complément qui ont été activés pour utiliser mes connexions existantes Active Directory Compte Directory Plutôt pour créer des comptes pour tout le monde, ce qui était un énorme, plus sur de l'autre des autres systèmes Wiki que j'ai trouvés . Il possède également le contrôle de la version typique, où vous pouvez voir qui a affiché ce que, et il a la possibilité de revenir à une version précédente si nécessaire. Ils incluent également une page d'accueil personnalisable qui, où YO peut facilement changer tout type de contenu convient le mieux à votre environnement.
Avec les plugins droits, TRAC peut devenir un billet de combinaison et un système wiki. Cela permet à vos billets de créer un lien avec les articles Wiki et inversement.
Quelques plugins que j'aime:
- Plugin de billets privés . TRAC est construit comme une bugbase où tous les billets et leurs réponses sont publics. Ce n'est pas approprié à un système de billets informatique, mais ce plugin corrige cela.
- plug-in TRAC WYSIWYG . Faisons face dessus, la plupart des gens ne vont pas apprendre Wikisyntax pour vous rendre heureux. Cela leur donne un "ce que tu vois est ce que tu obtiens" éditeur d'éditeur pour les pages de billets et wiki.
Il y a de nombreuses personnes plus personnalisations pour TRAC. Il n'est pas difficile de configurer et de personnaliser un système de TRAC à votre goût!
doku wiki ou SharePoint pour d'autres choses qui entrent dans un tableau.
Vous vous habituez assez vite à poster sur un wiki et la syntaxe n'est pas si complexe. Il est très facile d'organiser des informations et de la trouver facile de le trouver plus tard par quelqu'un d'autre.
J'utilise Visio pour faire des graphiques pour des explications plus claires (exportation comme JPEG).
Nous utilisons un wiki. En fait, nous utilisons Mediawiki. Au sommet de Mediawiki, nous avons la extension de Mediawiki sémantique installées, qui transforme réellement notre MediaWiki en quelque chose d'une base de données sans hésiter que nous pouvons interroger avec la catégorie, le titre, le contenu, etc.
Par exemple, disons que je souhaite voir tous les CNAMES de réseau qui acheminez via Cluster F. Tout ce que je dois faire est d'utiliser la page spéciale: demandez à la page à la requête [[Catégorie: CNAME]] [[Destination :: Cluster_f]] .. . Et cela retournera toutes les pages classées comme CName avec la destination comme Cluster_f.
Nous soutenons quelques centaines de clients très disparates, alors disposerons de cette documentation dans un lieu central (et de la réticuler réticulé de manière à ce que les cas spéciaux restent documentés et liés dans l'ensemble) soient une énorme chose pratique. De toute évidence, notre documentation doit être maintenue, mais vous pouvez prendre plus d'une approche "jardinier" de la maintenance, car la boîte à outils MediaWiki pour garder un grand courant de données est déjà assez mature.
Dans mon travail précédent, j'ai utilisé Twiki. Cela a fonctionné assez bien.
À côté de cela, j'ai tendance à automatiser la plupart des tâches et à documenter les scripts (pas toujours avec beaucoup d'enthousiasme, mais toujours ...). Les scripts de documentation sont facilement effectués dans le processus de les concevoir, donc pas de vrais frais généraux ...
La combinaison des deux (et d'utiliser la version de la version pour les scripts) a fait de l'astuce assez bien.
Un mélange de documents jira, confluence et mot.
Institutionnalisation des connaissances
Nous avons commencé avec des documents. Ensuite, nous avons enregistré certains d'entre eux dans les bibliothèques SharePoint. Puis récemment, nous avons déménagé au SharePoint Wiki. J'aime l'approche à faible frottement de la Wiki dans la mise à jour rapide des choses, bien que les wikis de SharePoint laissent des choses à désirer dans le support graphique et le formatage de la prise en charge des choses comme des tables. C'est bien pour le texte et l'éditeur intégré permet de formater des listes de formatage et de commande HTML de base/non ordonnées. Il existe d'autres alternatives à faible coût à SharePoint.
Nous avons également une sorte de base de connaissances informelle pour nos tickets de support dans notre logiciel de service d'assistance, la piste de Numara. Ce n'est pas parfait mais ça marche.
Obtenir du personnel à utiliser le savoir institutionnel
Je conviendrais avec votre évaluation que la connaissance institutionnalisée n'est qu'une partie de la bataille. Si votre organisation et votre peuple ne sont pas habitués à "rechercher d'abord, demandez-y à la seconde" alors vous constaterez que l'ancien chemin prévaut: tout le monde va toujours regarder les gourous formels et informels pour des réponses et que certaines personnes seront toujours plus faciles à poser la personne à côté de vous que de chercher seul.
Traiter avec cela impliquera une certaine gestion de changement; Comme la plupart des initiatives de changement réussies touchent plus qu'une petite équipe, cela aidera à avoir un aval et un soutien de la gestion. Vous devez vraiment forger de nouveaux comportements dans deux directions; Quelqu'un doit capter les connaissances et les personnes doivent l'utiliser. Même plus fort est que les gens doivent également garder ce courant de données.
Quelques idées: probablement, il faudra probablement être encouragé sous la forme d'une politique formelle indiquant que les billets résolus et les problèmes doivent être documentés dans la base de connaissances ou le wiki avant qu'ils puissent être considérés comme fermés. En outre, les chefs de connaissances qui ont normalement demandé des questions ne devraient pas toujours offrir des réponses sur demande; Ils ont besoin de pointer les gens vers les wikis et de les faire connaître pour y vérifier d'abord. Une autre chose serait de rendre les données à la disposition des utilisateurs pour l'auto-aide afin que la question puisse potentiellement être résolue avant de devenir un autre article que le personnel technique doit jongler.
Ce qui serait bien, c'est que notre système d'assistance ait un système similaire à Stackoverfloverflow et Serverfault: lorsque vous tapez une question, le moteur de recherche trouve des éléments similaires et les propose, afin que les utilisateurs puissent les regarder avant même de soumettre la question.
SharePoint est gentil.
Ses caractéristiques de recherche ont la possibilité d'indexer presque tout type de document, ce qui facilite la recherche de la documentation.
Il peut également effectuer des modèles, ce qui peut faciliter la tâche si vous avez par exemple une feuille d'informations standard pour chaque serveur que vous construisez.
Il peut également en protéger vos documents pour vous afin que vous ayez un historique d'audit des modifications de documentation.
De plus, les fichiers contenus dans les bibliothèques de document sont accessibles sur le Web, dans Outlook, ou via un partage UNC tout droit hors de la boîte.
Nous avons utilisé Mediawiki (avec FCKeditor) depuis plusieurs années, bien que je dois dire que ce serait bien si la manipulation des images (c.-à-d. Captures d'écran) était plus facile. Et tout en ayant la capacité de rechercher est essentiel - je trouve la recherche de Mediawiki me manque souvent des pages. Peut-être que c'est juste une question d'apprentissage à mieux chercher (qui défait le genre pour avoir un moyen simple pour les autres de faire votre travail)
À l'heure actuelle, nous sommes en train de parler de tout déplacer sur Mme SharePoint, bien que cela ne soit pas nécessairement à leur wiki. Je pense que SharePoint est capable de faire recherche de documents complète d'une manière qui nie certains des avantages d'un wiki, nous verrons donc où cela va.
(N'attendez pas avec impatience le processus de portant toute notre documentation actuelle :))
Nous utilisons un wiki. Bien sûr, la syntaxe a pris un peu pour s'habituer à, mais celle 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 catastrophe, car nous pouvons les restaurer n'importe où et les rechercher à partir de la ligne de commande via Grep et les lire dans n'importe quel éditeur de texte que nous aimons.
Chaque serveur dispose d'une page, avec une collection standard de sous-pages pour les informations sur la gestion des modifications, le démarrage/arrêt et les notes de configuration, ainsi que des informations DNS, pare-feu et Info.
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 sur un répertoire d'arbres, c'est mon memex et j'écris presque tout dessus (personnel, travail, etc. ). Ce schéma est très facile à gérer à l'aide de jedit Un vrai couteau suisse de l'armée pour le traitement de texte, j'ai trouvé son plug-in de contour, le pliage de code et l'hypersearch fonctionnalités indispensables. Tout cela sauvegardé en toute sécurité par RSYNC à un serveur distant accessible SSH.
Couple qui avec le Makelink Firefox Extension et vous avez le gestionnaire de signet parfait.
Nous nous préparons à passer à une version d'un service SharePoint pour tenter de nous faire passer un mélange de documents Word répartis sur trois serveurs et qui sait combien de dossiers. Actuellement, nous avons une feuille de calcul Excel massive contenant des hyperliens vers les documents qui sont décrits.
Ce n'est pas la meilleure façon de le faire, mais lorsque la société a commencé, elles n'ont jamais planifié la manière de gérer la documentation interne et de l'avoir laissée à chaque groupe de décider de trier et de stocker leur propre documentation lorsqu'ils ont vu l'ajustement. Maintenant, nous essayons de fusionner dans un système unifié, qui sera autour de l'une des offres SharePoint.
Cette question est très bien un duplicata de celui-ci et j'ai déplacé ma réponse là-bas.
Je n'ai pas vu cette question avant que je réponde ne autre question , mais ici nous allons.
Nous utilisons un certain nombre d'outils et de méthodes.
- Spécifications fonctionnelles pour composants d'infrastructure et logiciels.
- Deux Confluence wikis . Un pour la documentation d'entreprise interne (politiques, procédures, infrastructures internes et informatique, etc.) et une pour nos produits logiciels open source.
- RSPEC et concombre Tests. Notre logiciel est principalement écrit en rubis et nous pratiquons [~ # ~ # ~] BDD [~ # ~] / TDD , donc Les tests de spécification pilotent le code actuel et le document également.
- Documentation de code en ligne. Nous utilisons RDoc marquage dans les commentaires du code.
- Gestion de la configuration déclarative ( Chef ). Tous nos serveurs sont gérés avec le chef, qui "documents auto-automatiques" par le biais de ressources delcaratives dans des recettes et des livres de cuisine.
Nous aimons la confluence car il est très flexible et puissant et fonctionnel complet, plus il se lie dans le logiciel de gestion des billets que nous aimons, Jira .
Dans les entreprises précédentes, j'ai travaillé, j'ai utilisé une variété d'outils et de méthodes et beaucoup ont essayé de rester avec une seule ressource capture (comme un wiki) pour tout. Le problème de celui-ci documente divers sujets avec un seul outil ne convient pas particulièrement à couvrir ce sujet signifie que beaucoup de choses ne seront pas du tout documentées, car il est difficile de migrer les informations. En tant que geek Unix/Linux, je pense que chaque tâche nécessite un outil spécifique et que cet outil devrait correspondre à cette tâche extrêmement bien.
Nous utilisons une tourte pour le contenu et SharePoint pour stocker des documents/des images.
Il y a des choses intéressantes ici - J'aime celui des mots de passe dans un coffre-fort.
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 fonctionne sous Serverfault (bien, techniquement ce n'est pas exactement la même chose, mais pour notre objectif, nous pouvons supposer que c'est la même chose).
Fogbugz tilise-le .
Il y a un intéressant blog post d'un employé de Fogbugz où j'ai trouvé ces citations:
Pour tous les objectifs en dehors des spécifications de produits, je pense que les formes de discussion d'entreprise Wiki ont été traitées.
...
Depuis que nous avons commencé à utiliser Fogbugz.stackexchange.com comme plate-forme de support, 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 Q & A non publiques et les mêmes principes s'appliquent là.
Ils utilisent Stackexchange pour une base de connaissances confrontée à la clientèle et une base de connaissances interne.
Je suis intéressé de voir si de telles plateformes d'échange de connaissances sur les plateformes de questions-réponses remplaceront les sociétés Wiki.
Nous utilisons flexwiki , qui est un dotnet et une source open source.
Erm ... Que diriez-vous de Fogbugz? :)
Nous utilisons une combinaison de fichiers texte pour une recherche rapide avec GREP. Et SharePoint pour une collection plus organisée de documentation approfondie (diagrammes de visio, etc.).
En tant que clients Google Apps (Enterprise), nous utilisons les sites de Heck de Google - leur wiki "saveur". Facile à utiliser et nous avons eu une grande adoption d'administrateurs et de développeurs.
Nous utilisons MediaWiki avec divers plugins, y compris SemantesMediawiki. SMW est agréable car il transforme notre installation MediaWiki en une grande base de données relationnelle gratuite qui peut être interrogée à la volonté. Besoin de savoir quel serveur un site Web sur? Visitez sa page. Besoin de savoir quels sites Web sont hébergés sur un serveur? Exécutez une requête, et cela choisira les noms de page en fonction de la balise appropriée sur la page de chaque site Web.
Sur mon lieu de travail, j'ai laissé tomber Wiki Wiki sur l'un de nos serveurs Windows Dev et l'ai accroché à notre serveur SQL. Cela fonctionne vraiment bien, court rapidement et reste principalement sur notre chemin pour la documentation. Au cours des deux semaines qui a été déployée, nous avons déjà ajouté environ 60 pages d'information et ce n'est que pour notre équipe (environ 10 personnes).
Jusqu'à présent, nous conservons des informations sur les projets actuels et passés et ont commencé à ajouter des informations sur les applications telles que la manière de les construire à partir de zéro, d'URL et d'autres informations importantes pour Dev Nouveauté de l'équipe.
Une de mes pages préférées sur le wiki a été la page Outils et Bibliothèques. Nous avons commencé à ajouter des informations sur nos outils de productivité préférés et nos bibliothèques que nous utilisons beaucoup, dont le grepwin est de la recherche de texte dans Windows.
Je recommanderais pleinement de vérifier la gamme complète de Wiki disponible et de trouver un qui convient à votre utilisation, fonctionnalité et votre environnement de déploiement. J'ai choisi la piste car il est facile à utiliser et nous avons eu une tonne de chambre libre sur notre Winserver local, mais YMMV.
Essayez Redmine. Je l'ai utilisé pour les projets de groupe collège ainsi que des projets industriels.
Il comprend un soutien aux wikis, documents, notes, svn (je pense qu'ils travaillent sur GIT), demandes de fonctionnalités, suivi de bogues sophistiqués et tout est automatiquement ajouté à Gantt Graphiques pour surveiller le développement.
C'est une très belle plate-forme où vous pouvez ajouter différents niveaux d'utilisateurs (Devs, observateurs, utilisateurs, etc.) et partager de nombreuses informations entre tout le monde.
Nous utilisons Confluence comme wiki et SharePoint pour des documents dans certains cas. Je crois que le format de wiki en ligne est un format de wiki en ligne lorsque vous devez partager ces informations très largement et ce qui est beaucoup plus important lorsque les documents seront modifiés et mis à jour très souvent. Je pense donc que les articles de la base de connaissances, il vaut mieux mettre en wiki.
Nous ouvrons actuellement nos informations de divers documents diffusés autour du réseau à deux endroits:
- Un wiki disponible sur notre intranet
- Une copie des informations relatives à un serveur particulier dans ce répertoire de serveurs/racines.
Pour les diagrammes de réseau, Network Nethad .
En outre, tout en enregistrant ce que, rappelez-vous d'enregistrer pourquoi quelque chose est configuré comme celui-ci est. Cela aide à prévenir les idées qui semblent être une bonne idée de devenir des erreurs.
MindTouch Deki (également connu sous le nom de Dekiwiki ou "MindTouch") est mon choix ici, pour un certain nombre de raisons:
- il a l'air et fonctionne bien hors de la boîte, mais est également facilement extensible avec des extensions, des scripts ou des modèles
- il utilise un éditeur WYSIWYG, afin que les utilisateurs ne puissent pas utiliser "Je ne veux pas apprendre wikitext" comme une excuse pour ne pas documenter
- toutes les données sont stockées dans XML, ce qui signifie que chaque page peut être utilisée sous forme de service Web XML.
- aPI facile à utiliser, actionné avec REST (verbes http standard)
- langue de script fantastique, Dekiscript , faisant des mashups triviaux
- absolument belle PDF Sortie à l'aide - Prince , le moteur HTML/CSS des auteurs de CSS
Comment puis-je l'utiliser? En tant que base de connaissances complète, divisée en sections pour chaque département, avec des pages sous cela pour tout ce qui pourrait avoir besoin d'informations stockées à ce sujet!
En ce qui concerne les systèmes de surveillance de réseau, vous pouvez télécharger un ZENOSS/MindTouch Deki Mashup pour avoir placé des données en direct à partir d'une installation ZENOSS dans les pages Wiki MindTouch pour des notes de configuration et d'autres futurs mashups possibles.
L'édition Open Source est commercialisée comme "Core" et des fonctionnalités complémentaires de l'édition commerciale incluent des connecteurs pour des services tels que SugarCRM et Salesforce et des bases de données telles que Microsoft SQL Server. Les clients commerciaux ont également accès aux connecteurs Windows (Outlook/Word, etc.) et une application Dektop pour manipuler le wiki.
L'installation sur IIS est aussi simple que d'installer MySQL, puis d'installer un MSI. Le MSI n'est techniquement que pour l'édition d'entreprise, mais il y a Solution de contournement pour l'utiliser pour la construction open source. Une alternative consiste à installer l'appareil VM (surtout si vous avez déjà une infrastructure de serveur VMware), auquel cas vous n'avez vraiment besoin de configuration du tout.
Nous avons constaté que Mediawiki ait été un démarreur lent, mais une fois que les gens en dehors de celui-ci ont eu du vent de la facilité d'ajouter des commentaires, des modifications, des modifications, etc., il est devenu indispensable. Les développeurs l'utilisent pour la documentation interne, des installations. Pour afficher des avis, etc. Il est cultivé au-delà d'être un outil de documentation informatique.
À mon ancien employeur, j'ai utilisé des fichiers Word, Excel et Visio collectés ensemble dans un dossier. Une copie papier de tout a été conservée dans un classeur dans mon bureau. J'étais la seule personne informatique, alors il y avait peu de besoin que quiconque ait accès à l'information.
Dans mon employeur actuel, nous utilisons Macola ES par un logiciel exact, mais je préfère toujours écrire ma documentation dans Word et la télécharger en Macola en tant que pièce jointe que d'utiliser l'éditeur de document intégré.
Mediawiki ici aussi. Je suis le seul soutien informatique dans le cabinet de comptabilité que je travaille, donc à ce stade, je n'ai pas besoin de vous inquiéter de la collaboration. Malgré tout, je trouve qu'un wiki fonctionne étonnamment bien pour le type de changements rapides que je fais régulièrement.
Le problème que j'ai est que quelque chose de sensible (c.-à-d. Les mots de passe) sont stockés en dehors du wiki dans un stockage plus sûr, mais ce serait bien de l'avoir plus immédiatement disponible.