Frage Wie dokumentieren Sie Ihre Arbeit, Prozesse und Umgebung?


Benutzt du ein Wiki-Format? Wenn ja, welches Produkt? (MediaWiki, Confluence, Sharepoint etc.)

Haben Sie eine Wissensbasis geschaffen? (Problem- / lösungsorientierte kurze Dokumente.)

Welche Herausforderungen stellen Sie beim Erstellen einer funktionierenden Dokumentation dar, sodass Sie in den Ferien keinen Anruf erhalten?

Für mich ist es oft ein gewisses Maß an organisatorischer "Trägheit", die mit der Dokumentation verbunden ist. Es scheint eine andere Art von Person zu sein, die eine Aufgabe erledigen kann und dann darüber nachdenkt Wie Sie haben die Aufgabe gemacht und beschreiben sie so, dass jemand anderes es tun kann - eine Art von Kräften für Sie "gehen Meta" und nicht jeder ist komfortabel dabei.

Aktualisieren

Die Antworten enthalten bisher

  •  Zusammenfluss
  •  Flexwiki
  •  Fogbugz
  •  Mediawiki (mit Plugins wie fckeditor)
  •  Sharepoint
  •  TWiki
  •  Word- / Excel- / Visio-Dokumente
  •  Dokumentierte Skripte

Bearbeiten: Dokumentieren Sie nicht implizit Ihr Netzwerk mit Ihrem Überwachungssystem? Nagios hat immer die Verwendung der Eltern Richtlinie, um die Struktur Ihres Netzwerks zu reflektieren, und die Notizen_url Direktive soll es Ihnen ermöglichen, auf ein Wiki oder eine andere browserbasierte Dokumentation zu verlinken. Hier wird also die "Dokumentation" zwischen dem "lebenden Dokument" des Monitoring-Systems und einer detaillierteren Offline-Dokumentation in einem Wiki aufgeteilt. Da ich viel Zeit damit verbringe, Nagios anzustarren, ist es sinnvoll, sich darum zu bemühen, es so informativ wie möglich zu gestalten.


48
2018-06-04 04:59


Ursprung


Ihre Frage ist nur ein Schrägstrich tech.slashdot.org/article.pl?sid=09/5/25/2154237 - username
hehe :) Ich wünschte, ich könnte diese Frage irgendwie abschliessen, vielleicht warten, bis die Beta vorbei ist ... - Cawflands
Siehe den Abschnitt "Verwandte" in der Seitenleiste - serverfault.com/questions/3970/... könnte sein, was du suchst - Olaf
Überwachungssysteme wie Nagios sagen Ihnen, wie Ihr Netzwerk / System gerade aussieht. Sie sagen normalerweise nicht, warum das Netzwerk und die Systeme so eingerichtet sind, wie sie sind. - David


Antworten:


Kommentierung der Werkzeuge.

Wir haben Online-Wiki's ausprobiert, haben aber eine Reihe von Einschränkungen gefunden, die möglicherweise persönlicher Geschmack sind, aber die Dokumentstruktur einschließen und am kritischsten mit dem Dokumentationsserver verbunden sein müssen.

Die Verbindung ist ein ernstes Problem, wenn Sie entweder offline oder vor Ort sind (natürlich können Sie den Standort mit einer gesicherten SSL-Verbindung mildern.)

Unser aktueller Dokumentationsprozess ist:

  • Statischer HTML-Generator
  • Abschriften-Syntax
  • verteiltes Versionierungssystem

Wir haben ein 'formales' Layout für die Dokumentation und das bietet die Struktur für die Menüs (und das zugehörige CSS für visuelles Styling etc.)

Statischer HTML-Generator

Wir verwenden einen internen statischen HTML-Generator auf Basis von kubaltemp und eine Reihe anderer Werkzeuge: Segmente, Dokutils.

Die generierten Seiten sind (nicht?) Offensichtlich hässlich aussehend, da die meisten von uns / unsere Systemadministratoren / Programmierer wissen, was ästhetisch schön ist, aber einen völligen Mangel an Koordination beim Bauen solcher haben.

Aber es gibt uns Konfigurationsdateien, Beispielskripte, PDF usw., ohne dass wir uns Gedanken darüber machen müssen, ob es sich um eine HTML-Formatierung handelt oder ob wir uns Gedanken darüber machen, wo wir es auf dem "Server" zum Herunterladen finden.

Wenn es sich nicht um HTML handelt, lassen Sie es einfach in den Ordner fallen und fügen Sie einen URL-Link hinzu.

HTML bietet eine "potentielle" Struktur für das Layout und stellt auch eine kritische Verbindung zwischen Wissens- / Inhaltselementen (sowie Basisstrukturmechanismen wie das Erstellen von Menüs, Inhaltslisten usw.) her. Mit HTML kann jeder Benutzer jetzt renne einen kleinen Webserver auf ihrem Rechner ob lighttpd oder sowas klein oder gehe einfach voll mit Apache oder IIS.

Alle unsere Maschinen haben das Grunzen für grundlegende HTML-Serving und funktioniert gut genug für uns.

MARKDOWN-Syntax.

Wir verwenden eine Bastardversion von MARKDOWN, Textish und oder reStructuredTEXT um unsere "kreativen" Säfte schreiben zu lassen, ohne sich um HTML kümmern zu müssen.

Es bedeutet auch, dass jeder seinen Lieblings-Editor benutzen kann (ich benutze Scintilla unter Windows und * Nix), während die anderen hier vi / vim benutzen.

Verteiltes Versionierungssystem

Wir gebrauchen Git um die Dokumentation zwischen den Benutzern zu verteilen. Oh, und wir nutzen auch seine Versionierungsfähigkeit.

Der Hauptvorteil für uns ist, dass wir alle an der Aktualisierung der Dokumentation arbeiten können, ohne mit dem Server verbunden sein zu müssen, und ohne "abgeschlossene" Arbeiten veröffentlichen zu müssen. Wir können alle an den gleichen Teilen der Dokumentation oder an verschiedenen Teilen arbeiten oder einfach die Informationen konsumieren.

Persönlich hasse ich es, an einen Server gebunden zu sein, um Blogs zu aktualisieren, ganz zu schweigen von Wiki's. Git funktioniert gut für uns.

Kommentieren des Workflows

Wikis scheinen die "Mode" für die Wissensverbreitung / -kodifizierung zu sein, aber anderswo wird es schwierig, alle Prozesse aufrechtzuerhalten, und es wird Zeit brauchen, den Werkzeugmix zu finden, der die Bedürfnisse Ihres Teams am besten unterstützt und nachhaltig ist.

Die besseren Lösungen werden am Ende entdeckt und nicht vorgeschrieben.


8
2018-06-04 05:55



ich benutze ikiwiki oben auf Git. Gibt mir auch Markdown und getrennten Betrieb - ptman


Wir haben begonnen zu verwenden DokuWiki wo ich arbeite.

Von der Website von Dokuwiki:

DokuWiki ist standardkonform,   einfach zu bedienen Wiki, vor allem auf   Erstellung von Dokumentationen jeglicher Art Es   richtet sich an Entwicklerteams,   Arbeitsgruppen und kleine Unternehmen. Es hat   eine einfache aber mächtige Syntax, die   stellt sicher, dass die Datendateien erhalten bleiben   außerhalb des Wikis lesbar und erleichtert   die Erstellung von strukturierten Texten. Alles   Daten werden in einfachen Textdateien gespeichert -   keine Datenbank ist erforderlich.

Ich fand Dokuwiki am einfachsten zu implementieren, weil es keine Datenbank benötigt, und es war einfach einzurichten. Es gab auch Add-In-Module, die es ermöglichten, mein existierendes zu verwenden Active Directory-Kontoanmeldungen Anstatt dann Konten für alle zu erstellen, war das ein großer Vorteil gegenüber vielen anderen Wiki-Systemen, die ich gefunden habe. Es hat auch die typische Versionssteuerung, wo Sie sehen können, wer was wo gepostet hat, und es hat die Möglichkeit, bei Bedarf auf eine frühere Version zurück zu rollen. Sie enthalten auch eine anpassbare Homepage, auf der Sie ganz einfach auswählen können, welcher Inhalt für Ihre Umgebung am besten geeignet ist.


7
2018-05-04 13:31





Doku Wiki oder Sharepoint für andere Dinge, die in ein Diagramm passen.

Man gewöhnt sich ziemlich schnell an ein Wiki und die Syntax ist nicht wirklich komplex. Es ist sehr einfach, Informationen zu organisieren und es später leicht von jemand anderem zu finden.

Ich benutze visio, um Graphen für klarere Erklärungen zu erstellen (export als JPEG).


6
2018-05-04 13:53





Wir benutzen ein Wiki. Tatsächlich verwenden wir MediaWiki. Zusätzlich zu MediaWiki haben wir die Semantic Mediawiki Erweiterunginstalliert, was unser MediaWiki tatsächlich in eine lose typisierte Datenbank verwandelt, die wir mit Kategorie, Titel, Inhalt etc. abfragen können.

Nehmen wir zum Beispiel an, ich möchte alle Netzwerknamen sehen, die durch Cluster F routen. Alles, was ich tun muss, ist die Special: Ask-Seite, um [[Category: cname]] [[destination :: cluster_f]] abzufragen. und es gibt alle Seiten zurück, die als cname mit dem Ziel als cluster_f kategorisiert sind.

Wir unterstützen ein paar Hundert sehr unterschiedliche Kunden, so dass diese Dokumentation an einem zentralen Ort (und damit vernetzt, so dass die Sonderfälle dokumentiert und in das Ganze eingebunden bleiben) eine große praktische Sache ist. Natürlich muss unsere Dokumentation beibehalten werden, aber Sie können einen "Gärtner" -Ansatz für die Wartung verwenden, da das mediawiki-Toolkit für die Verwaltung eines großen Datensatzes bereits ziemlich ausgereift ist.


6
2018-05-04 14:04





Mit den richtigen Plugins Trac kann ein kombiniertes Ticket- und Wiki-System werden. So können Ihre Tickets leicht mit Wiki-Artikeln verlinkt werden und umgekehrt.

Ein paar Plugins die ich mag:

  • Plugin für private Tickets. Trac ist als Bugdatenbank aufgebaut, in der alle Tickets und ihre Antworten öffentlich sind. Das ist für ein IT-Ticket-System nicht geeignet, aber dieses Plugin behebt das.
  • Trac WYSIWYG-Plugin. Seien wir ehrlich, die meisten Leute werden Wikisyntax nicht lernen, um Sie glücklich zu machen. Dies gibt ihnen einen 'Was Sie sehen ist, was Sie bekommen' Editor für beide Tickets und Wiki-Seiten.

Es gibt einige Mehr Anpassungen für Trac. Es ist nicht schwer, ein Trac-System nach Ihren Wünschen zu erstellen und anzupassen!


6
2018-05-04 13:29



+1 dies. Tracs Wiki erleichtert nicht nur das Lesen und Bearbeiten von Dokumenten. In Verbindung mit dem Problem-Ticketing und SVN für die Konfigurationsversionierung haben Sie eine nahtlose Sichtbarkeit des gesamten Workflows. - Dan Carley


In meiner vorherigen Arbeit habe ich Twiki benutzt. Es hat ziemlich gut funktioniert.

Daneben tendiere ich dazu, die meisten Aufgaben zu automatisieren und die Skripte zu dokumentieren (nicht immer mit viel Begeisterung, aber trotzdem ...). Das Dokumentieren von Skripts ist während des Entwerfens einfach, also kein wirklicher Overhead ...

Die Kombination von beiden (und die Verwendung der Versionskontrolle für die Skripte) hat den Trick ziemlich gut gemacht.


5
2018-06-04 05:13





Eine Mischung aus JIRA, Confluence und Word-Dokumenten.


5
2018-05-04 13:45