Vraag Hoe documenteer je je werk, processen en omgeving?


Gebruik je een wiki-indeling? Zo ja, welk product? (MediaWiki, Confluence, Sharepoint, etc.)

Heb je een kennisbasis gecreëerd? (Probleem / oplossingsgerichte korte documenten.)

Welke uitdagingen vindt u bij het maken van documentatie die werkt, zodat u niet wordt gebeld als u op vakantie bent?

Voor mij zie ik dat er vaak een zekere mate van organisatorische "inertie" is bij het verkrijgen van documentatie. Het lijkt een ander soort persoon te zijn die een taak kan doen en er vervolgens aan kan denken hoe ze deden de taak en beschreef het zodat iemand anders het kan doen - soort van krachten voor jou "ga meta" en niet iedereen is comfortabel om dat te doen.

Bijwerken

Antwoorden tot nu toe omvatten

  •  Samenvloeiing
  •  Flexwiki
  •  FogBugz
  •  Mediawiki (met plug-ins zoals fckeditor)
  •  Deel punt
  •  TWiki
  •  Word / Excel / Visio Docs
  •  Gedocumenteerde scripts

Bewerk: Onderwerpt u niet impliciet uw netwerk aan uw bewakingssysteem? Nagios heeft altijd het gebruik van de ouders richtlijn om de structuur van uw netwerk weer te geven, en de notes_url richtlijn is ontworpen om u naar een wiki of andere browsergebaseerde documentatie te laten linken. Dus hier is de "documentatie" verdeeld tussen het "levende document" van het monitoringsysteem en meer gedetailleerde, offline documentatie in een wiki. Omdat ik veel tijd besteed aan het staren naar Nagios, is het logisch om moeite te doen om het zo informatief mogelijk te maken.


48
2018-06-04 04:59


oorsprong


je vraag is net slashdot geworden tech.slashdot.org/article.pl?sid=09/05/25/2154237 - username
hehe :) Ik wou dat ik deze vraag op de een of andere manier kon afsluiten, misschien wacht tot de bèta voorbij is ... - Cawflands
Zie de sectie "gerelateerd" in de zijbalk - serverfault.com/questions/3970/... is misschien wat je zoekt - Olaf
Bewakingssystemen zoals Nagios vertellen u hoe uw netwerk / systemen er op dit moment uitzien. Ze vertellen je meestal niet waarom het netwerk en de systemen zijn ingesteld zoals ze zijn. - David


antwoorden:


Een reactie op de tooling.

We hebben online wiki's geprobeerd, maar we hebben een aantal beperkingen gevonden, die een persoonlijke smaak kunnen zijn, maar die ook de documentstructuur bevatten en het meest kritisch verbonden moeten zijn met de documentatieserver.

Verbonden zijn is een serieus probleem als u offline of onsite bent (u kunt de onsite uiteraard verzachten met een beveiligde SSL-verbinding et al.)

Ons huidige documentatieproces is:

  • statische html-generator
  • markdown-syntaxis
  • gedistribueerd versiesysteem

We hebben een 'formele' lay-out voor de documentatie en die de structuur biedt voor de menu's (en de bijbehorende CSS voor visuele styling enz.)

Statische HTML-generator

We gebruiken een in-house statische html-generator op basis van cubictemp en een aantal andere hulpmiddelen: pygments, docutils.

De gegenereerde pagina's zijn (niet?) Duidelijk lelijk, omdat de meesten van ons / onze sysadmins / programmeurs weten wat esthetisch mooi is, maar een totaal gebrek aan coördinatie hebben bij het bouwen van dergelijke.

Maar het biedt ons / laten we ook configuratiebestanden, voorbeeldscripts, pdf, enz., Zonder ons zorgen te hoeven maken over het formatteren van html, of het zorgen over waar het op de 'server' te vinden is om te downloaden.

Als het geen HTML is, zet u het gewoon in de map en voegt u er een URL-link aan toe.

HTML biedt een 'potentiële' structuur voor lay-out en biedt ook een kritische koppeling tussen kennis / inhoudsitems (evenals basisstructuurmechanismen, zoals het kunnen maken van menu's, inhoudsopgaven enz.) Met HTML kan elke gebruiker nu een kleine webserver op hun computer draaien, of ze nu lighttpd of iets kleins zijn of gewoon voluit geblazen worden met Apache of IIS.

Al onze machines hebben de grunt voor het basishulpelen van HTML en werken goed genoeg voor ons.

MARKDOWN-syntaxis.

We gebruiken een verbasterde versie van MARKDOWN, Textish en of reStructuredText om onze 'creatieve' sappen documentatie te laten schrijven zonder zich zorgen te hoeven maken over HTML.

Het betekent ook dat iedereen zijn favoriete editor mag gebruiken (ik gebruik Scintilla op Windows en * Nix) terwijl de anderen hier vi / vim gebruiken.

Distributed Versioning System.

We gebruiken Git om de documentatie tussen gebruikers te 'verdelen'. Oh, en we gebruiken ook de versieningscapaciteit.

Het belangrijkste voordeel voor ons is dat we allemaal kunnen werken aan het bijwerken van de documentatie zonder verbonden te zijn met de server en zonder 'voltooide' werken te hoeven publiceren. We kunnen allemaal werken aan dezelfde delen van de documentatie of verschillende delen, of gewoon de informatie consumeren.

Persoonlijk vind ik het niet leuk om aan een server gebonden te zijn om blogs bij te werken, laat staan ​​wiki's. Git werkt goed voor ons.

Reageren op de workflow

Wiki's lijken de 'mode' te zijn voor kennisverspreiding / codificatie, maar zoals elders wordt opgemerkt, worden alle processen moeilijk houdbaar en het vinden van de mix van tools die het best aansluit bij de behoeften van uw teams en die duurzaam is, kost tijd.

De betere oplossingen worden uiteindelijk ontdekt en niet gemandateerd.


8
2018-06-04 05:55



ik gebruik ikiwiki bovenop git. Geeft me ook een afwaarnemings- en verbroken werking - ptman


We zijn begonnen te gebruiken DokuWiki waar ik werk.

Van de website van Dokuwiki:

DokuWiki voldoet aan de standaarden,   eenvoudig te gebruiken Wiki, voornamelijk gericht op   documentatie maken van welke aard dan ook. Het   is gericht op ontwikkelaarsteams,   werkgroepen en kleine bedrijven. Het heeft   een eenvoudige maar krachtige syntaxis die   zorgt ervoor dat de datafiles blijven   leesbaar buiten de Wiki en vergemakkelijkt   het creëren van gestructureerde teksten. Allemaal   gegevens worden opgeslagen in gewone tekstbestanden -   geen database vereist.

Ik vond dat Dokuwiki het gemakkelijkst te implementeren was omdat het geen database nodig had en het eenvoudig te installeren was. Er waren ook invoegtoepassingen die het mogelijk maakten om mijn bestaande te gebruiken Aanmeldingen van Active Directory-accounts in plaats van accounts te maken voor iedereen, wat een groot voordeel was ten opzichte van veel van de andere wikisystemen die ik vond. het heeft ook het typische versiebeheer, waar u kunt zien wie wat heeft gepost en het heeft de mogelijkheid om terug te gaan naar een vorige versie, indien nodig eenvoudig. Ze bevatten ook een aanpasbare startpagina waarmee u gemakkelijk kunt wijzigen welk type inhoud het beste past bij uw omgeving.


7
2018-05-04 13:31





Doku Wiki of Sharepoint voor andere dingen die in een diagram passen.

Je went vrij snel aan het plaatsen op een wiki en de syntaxis is niet zo complex. Het is heel eenvoudig om informatie te organiseren en het gemakkelijk te maken om het later door iemand anders te vinden.

Ik gebruik Visio om grafieken te maken voor duidelijkere uitleg (exporteren als JPEG).


6
2018-05-04 13:53





We gebruiken een wiki. We gebruiken zelfs MediaWiki. Bovenop MediaWiki hebben we de Semantic Mediawiki-extensiegeïnstalleerd, waardoor onze MediaWiki feitelijk verandert in iets van een losjes getypte database die we kunnen opvragen met Categorie, titel, inhoud, etc.

Laten we zeggen dat ik bijvoorbeeld alle netwerkcnames wil zien die door Cluster F gaan. Het enige dat ik moet doen is de Special: Ask-pagina gebruiken om te zoeken naar [[Category: cname]] [[destination :: cluster_f]] .. . en alle pagina's die zijn gecategoriseerd als een cname met de bestemming worden geclusterd als cluster_f.

We ondersteunen een paarhonderd zeer uiteenlopende klanten, dus die documentatie op een centrale plaats hebben (en het kruislings koppelen, zodat de speciale gevallen gedocumenteerd blijven en in het geheel worden vastgehouden) is een enorm handig iets. Vanzelfsprekend moet onze documentatie worden bijgehouden, maar je kunt een meer 'tuinman'-benadering hanteren voor het onderhoud, omdat de mediawiki-toolkit voor het bijhouden van een grote dataset-stroom al redelijk volwassen is.


6
2018-05-04 14:04





Met de juiste plug-ins, Trac kan een combinatieticket en wikisysteem worden. Dit maakt het gemakkelijk om uw tickets te linken naar wiki-artikelen en omgekeerd.

Een paar plug-ins die ik leuk vind:

  • Private Tickets-plug-in. Trac is gebouwd als een bugbase waar alle tickets en hun antwoorden openbaar zijn. Dat is niet geschikt voor een IT-ticketsysteem, maar deze plug-in repareert dat.
  • Trac WYSIWYG-plug-in. Laten we eerlijk zijn, de meeste mensen zullen geen wikisyntax leren om je gelukkig te maken. Dit geeft ze een 'wat je ziet is wat je krijgt'-editor voor zowel tickets als wiki-pagina's.

Er zijn er nogal wat meer aanpassingen voor Trac. Het is niet moeilijk om een ​​Trac-systeem naar wens in te stellen en aan te passen!


6
2018-05-04 13:29



+1 dit. Niet alleen maakt de wiki van Trac het gemakkelijk om te lezen en te bewerken voor documentatie. Bij gebruik met issuekaartjes en SVN voor configuratieversies, hebt u een naadloze zichtbaarheid van de gehele workflow. - Dan Carley


In mijn vorige werk gebruikte ik Twiki. Het werkte redelijk goed.

Daarnaast heb ik de neiging om de meeste taken te automatiseren en de scripts te documenteren (niet altijd met veel enthousiasme, maar toch ...). Het documenteren van scripts is eenvoudig tijdens het ontwerpen, dus geen echte overhead ...

De combinatie van beide (en met behulp van versiebeheer voor de scripts) deed het redelijk goed.


5
2018-06-04 05:13





Een mix van JIRA, Confluence en Word-documenten.


5
2018-05-04 13:45





Kennis institutionaliseren

We zijn begonnen met documenten. Daarna hebben we een aantal van hen opgeslagen in Sharepoint-bibliotheken. Onlangs zijn we verhuisd naar de Sharepoint-wiki. Ik vind de wrijvingsarme aanpak van de wiki erg handig bij het snel bijwerken van dingen, hoewel de wiki's van Sharepoint wat te wensen overlaten in grafische ondersteuning en opmaakondersteuning voor zaken als tabellen. Het is prima voor tekst en de ingebouwde editor maakt enkele standaard HTML-opmaak en geordende / ongeordende lijsten mogelijk. Er zijn andere goedkope alternatieven voor Sharepoint.

We hebben ook een soort van informele kennisbasis voor onze support tickets in onze helpdesksoftware, Numara's Track-It. Het is niet perfect, maar het werkt.

Gebruik van personeel om geïnstitutionaliseerde kennis te verkrijgen

Ik ben het eens met uw inschatting dat geïnstitutionaliseerde kennis slechts een deel van de strijd is. Als uw organisatie en mensen niet gewend zijn om "eerst onderzoek te doen, om een ​​tweede vraag te stellen", zult u merken dat de oude manier de overhand heeft: iedereen zal nog steeds naar de formele en informele goeroes kijken voor antwoorden, en voor sommige mensen zal het altijd gemakkelijker zijn om te vragen de persoon naast je dan om alleen te zoeken.

Om dit aan te pakken, zal een aantal veranderingen nodig zijn; zoals de meeste succesvolle veranderingsinitiatieven die van invloed zijn op meer dan alleen een klein team, zal het helpen om goedkeuring en ondersteuning door het management te krijgen. Je moet echt nieuw gedrag in twee richtingen smeden; iemand moet de kennis vastleggen en mensen moeten het gebruiken. Nog moeilijker is dat mensen ook die gegevens actueel moeten houden.

Enkele ideeën: waarschijnlijk moet er een aanmoediging zijn in de vorm van een formeel beleid waarin wordt gesteld dat opgeloste tickets en problemen moeten worden gedocumenteerd in de kennisbank of wiki voordat ze als gesloten kunnen worden beschouwd. Bovendien zouden de kennisleiders die normaal gesproken vragen krijgen, niet altijd op vraag antwoorden moeten bieden; ze moeten mensen naar de wiki's wijzen en ze daar eerst laten wennen aan het controleren. Een ander ding zou zijn om gegevens beschikbaar te maken voor gebruikers voor zelfhulp, zodat het probleem mogelijk kan worden opgelost voordat het weer een item wordt dat het technische personeel moet jongleren.

Wat wel leuk zou zijn, is dat ons helpdesksysteem een ​​systeem heeft dat vergelijkbaar is met StackOverflow en ServerFault: bij het typen van een vraag vindt de zoekmachine vergelijkbare items en biedt deze aan, zodat gebruikers ernaar kunnen kijken nog voordat de vraag is ingediend.


5
2018-06-04 05:46



+1: waar ik werk, was het een soortgelijk probleem om personeel middelen te laten gebruiken, meer bepaald, het gebruikte het probleemopsporingssysteem om problemen te krijgen. Uiteindelijk nam ik de mensen die moeite hadden met het veranderen van hun gewoonte om me de eerste keren terug te stoten naar mijn bureau en een nieuw bug-ticket bij hen in te vullen. Duurde 2 maanden en nu komt iedereen zijn eigen beestjes binnen en worden ze allemaal op volgorde verzorgd. Een vergelijkbare aanpak kan hier van pas komen (dus zoek naar het document in kwestie in het [systeem] MET hen) - Steven Evers