Wie dokumentieren Sie Ihre Arbeit, Prozesse und Umgebung?

48

Verwenden Sie ein Wiki-Format? Wenn ja, welches Produkt? (MediaWiki, Confluence, Sharepoint usw.)

Haben Sie eine Wissensbasis erstellt? (Problem- / lösungsorientierte Kurzdokumente.)

Welche Herausforderungen haben Sie mit der Erstellung einer Dokumentation, die funktioniert, sodass Sie im Urlaub nicht angerufen werden können?

Für mich gibt es oft eine gewisse organisatorische "Trägheit", die mit der Erledigung der Dokumentation verbunden ist. Es scheint eine andere Art von Person zu sein, die eine Aufgabe erledigen kann, dann darüber nachdenkt, wie sie die Aufgabe erledigt hat und sie beschreibt, damit es jemand anderes tun kann.

Aktualisieren

Bisherige Antworten sind:

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

Bearbeiten: Dokumentieren Sie Ihr Netzwerk nicht implizit mit Ihrem Überwachungssystem? Nagios hat immer die Verwendung der ermutigt Eltern Richtlinie zur Struktur des Netzwerks zu reflektieren und die notes_url Richtlinie soll Ihnen ein Wiki oder andere Browser-basierte Dokumentation Link zu ermöglichen. Die "Dokumentation" ist hier also aufgeteilt in das "lebende Dokument" des Überwachungssystems und eine detailliertere, Offline-Dokumentation in einem Wiki. Da ich viel Zeit damit verbringe, Nagios anzustarren, ist es sinnvoll, alles so informativ wie möglich zu gestalten.

Andrew H
quelle
Ihre Frage einfach gemacht slashdot tech.slashdot.org/article.pl?sid=09/05/25/2154237
Benutzername
hehe :) Ich wünschte, ich könnte diese Frage irgendwie abschließen, vielleicht warten, bis die Beta vorbei ist ...
Cawflands
Siehe "Verwandte" in der Seitenleiste - serverfault.com/questions/3970/… könnte das sein, wonach Sie suchen
Olaf
Überwachungssysteme wie Nagios zeigen Ihnen, wie Ihr Netzwerk / Ihre Systeme derzeit aussehen. In der Regel erfahren Sie nicht, warum das Netzwerk und die Systeme so eingerichtet sind, wie sie sind.
David

Antworten:

8

Das Werkzeug kommentieren.

Wir haben Online-Wikis ausprobiert, haben jedoch eine Reihe von Einschränkungen festgestellt, die möglicherweise auf den persönlichen Geschmack zurückzuführen sind, die jedoch die Dokumentstruktur einschließen und am kritischsten die Verbindung zum Dokumentationsserver erfordern.

Eine Verbindung herzustellen ist ein ernstes Problem, wenn Sie entweder offline oder vor Ort sind (natürlich können Sie die Vor-Ort-Situation mit einer gesicherten SSL-Verbindung ua abschwächen.)

Unser aktueller Dokumentationsprozess ist:

  • statischer HTML-Generator
  • Abschriftensyntax
  • verteiltes Versionierungssystem

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

Statischer HTML-Generator

Wir verwenden einen internen statischen HTML-Generator, der auf cubictemp und einer Reihe anderer Tools basiert : pygments , docutils .

Die generierten Seiten sehen (nicht?) Offensichtlich hässlich aus, da die meisten von uns / unseren Systemadministratoren / Programmierern zwar wissen, was ästhetisch schön ist, es jedoch an Koordination mangelt, solche zu erstellen.

Aber es bietet / lasst uns Konfigurationsdateien, Beispielskripte, PDFs usw. einbinden, ohne sich Gedanken darüber machen zu müssen, ob die HTML-Formatierung es vermasselt oder wo es auf dem "Server" zum Herunterladen zu finden ist.

Wenn es sich nicht um HTML handelt, legen Sie es einfach im Ordner ab und fügen Sie einen URL-Link hinzu.

HTML bietet eine "potenzielle" Struktur für das Layout und bietet auch eine "Verknüpfung" zwischen Wissens- / Inhaltselementen (sowie Basisstrukturmechanismen, wie z. B. die Möglichkeit, Menüs, Inhaltsverzeichnisse usw. zu erstellen). Mit HTML kann nun jeder Benutzer Führen Sie einen kleinen Webserver auf Ihrem Computer aus, egal ob Lighttpd oder ein kleiner Server, oder nutzen Sie Apache oder IIS.

Alle unsere Maschinen haben das Grunzen für einfaches HTML-Servieren und funktionieren gut genug für uns.

MARKDOWN-Syntax.

Wir verwenden eine bastardisierte Version von MARKDOWN, Textish und / oder reStructuredTEXT , damit unsere kreativen Säfte Dokumentation schreiben können, ohne sich um HTML kümmern zu müssen.

Es bedeutet auch, dass jeder seinen Lieblingseditor verwenden kann (ich verwende Scintilla unter Windows und * Nix), während die anderen hier vi / vim verwenden.

Distributed Versioning System.

Wir verwenden Git , um die Dokumentation zwischen den Benutzern zu "verbreiten". Oh, und wir nutzen auch die Versionierungskapazität.

Der entscheidende Vorteil für uns ist, dass wir alle an der Aktualisierung der Dokumentation arbeiten können, ohne mit dem Server verbunden zu sein 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 nur die Informationen konsumieren.

Persönlich hasse ich es, an einen Server gebunden zu sein, um Blogs zu aktualisieren, geschweige denn Wikis. Git funktioniert gut für uns.

Kommentieren des Workflows

Wikis scheinen die "Mode" für die Verbreitung / Kodifizierung von Wissen zu sein, aber wie an anderer Stelle ausgeführt, sind alle Prozesse nur schwer aufrechtzuerhalten, und es wird einige Zeit in Anspruch nehmen, den Werkzeugmix zu finden, der die Anforderungen Ihres Teams am besten unterstützt und nachhaltig ist.

Die besseren Lösungen werden einfach entdeckt und nicht beauftragt.

SAMT
quelle
1
Ich benutze ikiwiki auf git.
Gibt
7

Wir haben damit begonnen, DokuWiki zu verwenden, wo ich arbeite.

Von Dokuwikis Website:

DokuWiki ist ein standardkonformes, benutzerfreundliches Wiki, das hauptsächlich darauf abzielt, Dokumentationen jeglicher Art zu erstellen. Es richtet sich an Entwicklerteams, Arbeitsgruppen und kleine Unternehmen. Es verfügt über eine einfache, aber leistungsstarke Syntax, die sicherstellt, dass die Datendateien außerhalb des Wikis lesbar bleiben und die Erstellung von strukturierten Texten erleichtert. Alle Daten werden in Klartextdateien gespeichert - es ist keine Datenbank erforderlich.

Ich fand Dokuwiki am einfachsten zu implementieren, da es keine Datenbank benötigt und einfach einzurichten war. Es gab auch Add-In-Module, die es ermöglichten, meine vorhandenen Active Directory-Kontoanmeldungen zu verwenden, anstatt Konten für alle zu erstellen. Dies war ein großer Vorteil gegenüber den meisten anderen Wiki-Systemen, die ich gefunden habe. Es hat auch die typische Versionskontrolle, mit der Sie sehen können, wer was wo gepostet hat, und es hat die Möglichkeit, bei Bedarf einfach auf eine frühere Version zurückzukehren. Dazu gehört auch eine anpassbare Homepage, auf der Sie leicht die Inhalte ändern können, die für Ihre Umgebung am besten geeignet sind.

mrTomahawk
quelle
6

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

Man gewöhnt sich ziemlich schnell an das Posten in einem Wiki und die Syntax ist nicht wirklich so komplex. Es ist sehr einfach, Informationen zu organisieren und sie später für andere leicht zu finden.

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

Antoine Benkemoun
quelle
6

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

Angenommen, ich möchte alle Netzwerk-C-Namen sehen, die über Cluster F geleitet werden. Ich muss lediglich die Seite Special: Ask verwenden, um [[Kategorie: C-Name]] [[Ziel :: Cluster_f]] abzufragen. und es werden alle Seiten zurückgegeben, die als cname mit dem Ziel cluster_f kategorisiert sind.

Wir betreuen ein paar hundert sehr unterschiedliche Kunden, daher ist es sehr praktisch, diese Dokumentation an einem zentralen Ort zu haben (und sie zu vernetzen, damit die Sonderfälle dokumentiert und in das Ganze eingebunden bleiben). Natürlich muss unsere Dokumentation gewartet werden, aber Sie können die Wartung eher nach dem Prinzip eines „Gärtners“ durchführen, da das MediaWiki-Toolkit zum Aktualisieren eines großen Datensatzes bereits ziemlich ausgereift ist.

Karl Katzke
quelle
6

Mit den richtigen Plugins kann Trac zu einem kombinierten Ticket- und Wiki-System werden. Auf diese Weise können Ihre Tickets leicht auf Wiki-Artikel verlinken und umgekehrt.

Ein paar Plugins, die mir gefallen:

  • Plugin für private Tickets . Trac ist eine Bugbase, in der alle Tickets und ihre Antworten öffentlich sind. Das passt nicht zu einem IT-Ticketsystem, aber dieses Plugin behebt das.
  • Trac WYSIWYG-Plugin . Seien wir ehrlich, die meisten Leute werden Wikisyntax nicht lernen, um dich glücklich zu machen. Dies gibt ihnen einen Editor für Tickets und Wiki-Seiten, mit dem Sie sehen, was Sie bekommen.

Es gibt durchaus ein paar mehr Anpassungen für Trac. Es ist nicht schwer, ein Trac-System nach Ihren Wünschen einzurichten und anzupassen!

quux
quelle
1
+1 dies. Das Wiki von Trac erleichtert nicht nur das Lesen und Bearbeiten für Dokumentationen. In Verbindung mit Issue Ticketing und SVN für die Versionierung der Konfiguration haben Sie eine nahtlose Sicht auf den gesamten Workflow.
Dan Carley
5

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

Außerdem neige ich dazu, die meisten Aufgaben zu automatisieren und die Skripte zu dokumentieren (nicht immer mit viel Enthusiasmus, aber trotzdem ...). Das Dokumentieren von Skripten ist beim Entwerfen einfach, sodass kein wirklicher Aufwand entsteht.

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

Vincent De Baere
quelle
5

Eine Mischung aus JIRA, Confluence und Word-Dokumenten.

Andrew
quelle
5

Wissen institutionalisieren

Wir begannen mit Dokumenten. Dann haben wir einige von ihnen in Sharepoint-Bibliotheken gespeichert. Dann sind wir kürzlich ins Sharepoint-Wiki umgezogen. Ich mag den reibungslosen Ansatz des Wikis, wenn es darum geht, Dinge schnell zu aktualisieren, obwohl die Wikis von Sharepoint einige Wünsche in Bezug auf Grafikunterstützung und Formatierungsunterstützung für Dinge wie Tabellen offen lassen. Es ist in Ordnung für Text und der eingebaute Editor erlaubt einige grundlegende HTML-Formatierungen und geordnete / ungeordnete Listen. Es gibt andere kostengünstige Alternativen zu Sharepoint.

Wir haben auch eine informelle Wissensbasis für unsere Support-Tickets in unserer Helpdesk-Software, Numara's Track-It. Es ist nicht perfekt, aber es funktioniert.

Mitarbeiter dazu bringen, institutionalisiertes Wissen zu nutzen

Ich stimme Ihrer Einschätzung zu, dass die Institutionalisierung von Wissen nur ein Teil des Kampfes ist. Wenn Ihre Organisation und Ihre Mitarbeiter nicht daran gewöhnt sind, "zuerst zu recherchieren, dann fragen Sie", werden Sie feststellen, dass der alte Weg vorherrscht: Jeder wird sich immer noch an die formellen und informellen Gurus wenden, um Antworten zu erhalten, und für einige Menschen wird es immer einfacher sein, Fragen zu stellen die Person neben dir als auf eigene Faust zu suchen.

Der Umgang mit diesem Problem erfordert ein gewisses Änderungsmanagement. Wie bei den meisten erfolgreichen Veränderungsinitiativen, die mehr als nur ein kleines Team betreffen, ist es hilfreich, Unterstützung und Unterstützung durch das Management zu erhalten. Man muss wirklich ein neues Verhalten in zwei Richtungen entwickeln. jemand muss das Wissen erfassen und die Leute müssen es nutzen. Noch schwieriger ist es, diese Daten aktuell zu halten.

Nur ein paar Ideen: Möglicherweise muss eine formelle Richtlinie ermutigt werden, wonach gelöste Tickets und Probleme in der Wissensdatenbank oder im Wiki dokumentiert werden müssen, bevor sie als geschlossen betrachtet werden können. Darüber hinaus sollten die Wissensmanager, denen normalerweise Fragen gestellt werden, nicht immer nur auf Anfrage Antworten anbieten. Sie müssen die Leute auf die Wikis hinweisen und sie daran gewöhnen, zuerst dort nachzuschauen. Eine andere Sache wäre, den Benutzern Daten zur Selbsthilfe zur Verfügung zu stellen, damit das Problem möglicherweise gelöst werden kann, bevor es zu einem weiteren Punkt wird, den das technische Personal zu bewältigen hat.

Schön wäre, wenn unser Helpdesk-System ein ähnliches System wie StackOverflow und ServerFault hätte: Wenn Sie eine Frage eingeben, findet die Suchmaschine ähnliche Elemente und bietet sie an, sodass die Benutzer sie bereits vor dem Absenden der Frage anzeigen können.

Bernard Dy
quelle
+1: Wo ich arbeite, war es ein ähnliches Problem, Mitarbeiter dazu zu bringen, Ressourcen zu nutzen, obwohl es speziell darum ging, Probleme mithilfe des Fehlerverfolgungssystems zu erkennen. Am Ende nahm ich die Leute mit, die Schwierigkeiten hatten, ihre Gewohnheit zu ändern, mich das erste Mal wieder an meinen Schreibtisch zu stören, und füllte mit ihnen ein neues Bug-Ticket aus. Dauerte 2 Monate und jetzt trägt jeder seine eigenen Fehler ein und sie werden alle in Ordnung gebracht. Ein ähnlicher Ansatz könnte hier nützlich sein (dh suchen Sie das betreffende Dokument im [System] mit ihnen)
Steven Evers
4

An meinen letzten beiden Arbeitsorten habe ich das Wiki von Sharepoint sowie eine Dokumentbibliothek verwendet, die bestimmte Dokumente enthielt (z. B. DRPs und Pläne für einmalige Upgrades), die nicht einfach als Wiki-Dokumente erstellt werden können. Diese Dokumente hatten Links aus dem Wiki. Wiki hat in diesem Bereich viele Vorteile, da es von vielen Personen bearbeitet werden kann, die Versionierung integriert, leicht durchsuchbar und zugänglich ist usw. Zum schnellen Aufschreiben von Notizen oder Ideen würde ich OneNote oder ein Whiteboard verwenden.

Ich hatte zuvor einige Wissensdatenbanken im Forum-Format (sowohl in Lotus Notes als auch in MS Sharepoint) erstellt, aber ich muss sagen, dass nur selten Leute durch sie schauen, um zu sehen, ob ein bestimmtes Problem bereits gelöst wurde. Eine solche Lösung muss vom ersten Tag an mit einer sehr starken und effektiven Suchmaschine kommen.

Wenn Sie Dokumente erstellen möchten, die im Urlaub verwendet werden können, schreiben Sie sie so, als würden Sie versuchen, einen Ihrer Eltern zu unterweisen. Dies ist nicht 100% narrensicher, hilft aber manchmal. Kommt darauf an, wer es liest.

Moshe
quelle
Ich bin damit einverstanden, dass eine gute Suche für die Verwendung dieser Tools von entscheidender Bedeutung ist. Eine anständige Suche in Sharepoint wurde kürzlich von einem Kollegen durchgeführt. Es ist in Ordnung, aber nicht von Google.
Cawflands
4

Sharepoint ist nett.

Mit den Suchfunktionen können nahezu alle Dokumenttypen indiziert werden, wodurch das Durchsuchen der Dokumentation sehr einfach wird.

Es kann auch einige Vorlagen enthalten, die die Arbeit erleichtern, wenn Sie beispielsweise für jeden von Ihnen erstellten Server ein Standard-Informationsblatt haben.

Es kann auch Ihre Dokumente für Sie versionieren, sodass Sie einen Prüfverlauf der Dokumentationsänderungen haben.

Darüber hinaus können die in den Dokumentbibliotheken enthaltenen Dateien über das Internet, Outlook oder über eine sofort einsatzbereite Freigabe abgerufen werden.

Dominic D
quelle
3

Wir verwenden MediaWiki (mit fckeditor) seit einigen Jahren, obwohl ich sagen muss, dass es schön wäre, wenn die Handhabung von Bildern (dh Screenshots) einfacher wäre. Und obwohl die Möglichkeit zur Suche unerlässlich ist, fehlen bei der Suche mit MediaWiki häufig Seiten. Vielleicht ist es nur eine Frage des Lernens, besser zu suchen (welche Art von Niederlage hat den Zweck, anderen eine einfache Möglichkeit zu bieten, ihre Arbeit zu erledigen)

Im Moment befinden wir uns in Gesprächen darüber, alles auf MS Sharepoint zu verlagern , obwohl dies nicht unbedingt in deren Wiki erforderlich ist. Ich denke, Sharepoint ist in der Lage, eine vollständige Dokumentensuche durchzuführen , die einige der Vorteile eines Wikis zunichte macht. Wir werden also sehen, wohin das führt.

(Ich freue mich aber nicht darauf, all unsere aktuellen Dokumentationen zu portieren :))

Brent
quelle
1
Ich habe gelesen, dass Sphinx eine würdige Ergänzung zu einer MW-Installation ist, um die Suche zu verbessern.
Cawflands
3

Wir benutzen ein Wiki. Sicher, die Syntax war etwas gewöhnungsbedürftig, aber die von uns verwendete (Twiki) speichert ihre Daten vollständig als Textdateien. Dies ermöglicht es uns, sie im Katastrophenfall einfach zu lesen, da wir sie überall wiederherstellen und sie über die Befehlszeile mit grep durchsuchen und in einem beliebigen Texteditor lesen können.

Jeder Server verfügt über eine Seite mit einer Standardauflistung von Unterseiten für Änderungsverwaltungsinformationen, Start / Herunterfahren und Konfigurationshinweise sowie DNS-, Firewall- und Asset-Informationen.

Laura Thomas
quelle
2

Wir bereiten uns darauf vor, auf eine Version eines Sharepoint-Dienstes umzusteigen, um eine Mischung aus Word-Dokumenten zu erhalten, die auf drei Servern verteilt sind und die wissen, wie viele Ordner es gibt. Derzeit verfügen wir über eine umfangreiche Excel-Tabelle, die Hyperlinks zu den darin beschriebenen Dokumenten enthält.

Dies ist nicht der beste Weg, aber als das Unternehmen anfing, planten sie nie, wie sie mit der internen Dokumentation umgehen sollten, und überließen es jeder Gruppe, zu entscheiden, wie sie ihre eigene Dokumentation sortieren und speichern sollten, wie sie es für richtig hielten. Jetzt versuchen wir, uns zu einem einheitlichen System zusammenzuschließen, das eines der Sharepoint-Angebote sein wird.

user41811
quelle
2

In der NGO, in der ich arbeite, verwenden wir nur Textdateien, die in einem Ordner für kritische Vorgänge abgelegt sind. Persönlich habe ich als Systemadministrator / Webentwickler-Hybrid eine Wissensbasis von Textdateien verwendet, die in einem Baumverzeichnis verstreut sind. Das ist mein Memex, und ich schreibe fast alles darauf (persönlich, beruflich usw.). Dieses Schema ist mit Jedit, einem echten Schweizer Taschenmesser für die Textverarbeitung, sehr einfach zu verwalten. Ich habe festgestellt, dass das Gliederungs-Plug-in, das Falten von Codes und die Hypersuche unverzichtbar sind. All dies wird durch rsync sicher auf einem mit ssh erreichbaren Remote-Server gesichert.

Alt-Text

Wenn Sie das mit der Makelink Firefox-Erweiterung kombinieren , haben Sie den perfekten Lesezeichen-Manager.

cgomezsilva
quelle
1

Wir verwenden flexwiki , ein Dotnet und Open Source.

James Moore
quelle
1

Ähm ... wie wäre es mit Fogbugz? :)

Chopper3
quelle
1

Wir verwenden ScrewTurn für Inhalte und SharePoint zum Speichern von Dokumenten / Bildern.

Jeff
quelle
1

Es gibt einige interessante Dinge hier - i wie die über die Passwörter in einem Safe.

Preet Sangha
quelle
1

Wir verwenden eine Kombination von Textdateien für die schnelle Suche mit grep. Und SharePoint für eine übersichtlichere Sammlung ausführlicherer Dokumentationen (Visio-Diagramme usw.).

TCampbell
quelle
1

Als Google Apps (Enterprise) -Clients verwenden wir das Heck von Google Sites - ihre Wiki-"Variante". Einfach zu bedienen und von Administratoren und Entwicklern sehr gut angenommen.

Chris_K
quelle
1

Ich habe diese Frage nicht gesehen, bevor ich eine andere Frage beantwortet habe , aber jetzt geht es los.

Wir verwenden eine Reihe von Tools und Methoden.

  • Funktionsspezifikationen für Infrastrukturkomponenten und Software.
  • Zwei Confluence Wikis . Eine für die unternehmensinterne Dokumentation (Richtlinien, Verfahren, interne Infrastruktur und IT usw.) und eine für unsere Open-Source-Softwareprodukte.
  • RSpec und Gurken - Tests. Unsere Software ist größtenteils in Ruby geschrieben, und wir üben BDD / TDD , sodass Spezifikationstests den tatsächlichen Code und das Dokument ebenfalls testen.
  • Inline-Code-Dokumentation. Wir verwenden RDoc- Markup in Codekommentaren.
  • Deklaratives Konfigurationsmanagement ( Chef ). Alle unsere Server werden von Chefkoch verwaltet, der sich durch delkarative Ressourcen in Rezepten und Kochbüchern "selbst dokumentiert".

Wir mögen Confluence, weil es sehr flexibel und leistungsfähig ist und über alle Funktionen verfügt. Außerdem ist es mit der Ticket-Management-Software Jira verbunden, die wir mögen .

In früheren Unternehmen, in denen ich gearbeitet habe, habe ich eine Vielzahl von Tools und Methoden verwendet und viele haben versucht, für alles bei einer einzigen Sammelressource (wie einem Wiki) zu bleiben. Das Problem dabei ist, dass verschiedene Themen mit einem einzigen Tool dokumentiert werden, das nicht speziell für die Behandlung dieses Themas geeignet ist. Viele Dinge werden daher überhaupt nicht dokumentiert, da es schwierig ist, die Informationen zu migrieren. Als Unix / Linux-Freak bin ich der Meinung, dass für jede Aufgabe ein bestimmtes Tool erforderlich ist und dass dieses Tool für diese Aufgabe außerordentlich gut geeignet sein sollte.

jtimberman
quelle
1

Diese Frage ist sehr gut ein Duplikat von dieser und ich habe meine Antwort dorthin verschoben.

jtimberman
quelle
1

Ich mache den größten Teil der Dokumentation für mein Unternehmen, und das Format, das festgelegt wurde, als ich anfing, hier zu arbeiten, war MS Word für bearbeitbare Originale, exportiert als PDF-Datei für nur lesbare allgemeine Veröffentlichungen. Es funktioniert ziemlich gut für Projekte, bei denen nur eine Person das Dokument aktualisiert, und da es sich in der Regel um mich handelt, hat das Management keinen Änderungsbedarf festgestellt.

Wir haben angefangen, unsere Fehler und anstehenden Aufgaben mit Trac zu dokumentieren , während wir eine "Peer Review" -Erweiterung für Codeüberprüfungen verwenden. Das hat in unserem Team große Akzeptanz gefunden, da es einfach zusammenzuarbeiten und einfach zu navigieren ist. Einige andere Teammitglieder haben den Wunsch geäußert, verstärkt mit Spezifikationen, Testverfahren und Handbüchern zusammenzuarbeiten. Daher untersuchen wir DocBook / XML, das für öffentliche Dokumentationen wie Handbücher in PDF exportiert wurde, und Trac WIKI-Seiten für interne Dokumente wie Spezifikationen und Testverfahren.

In meinen Augen sind die größten Probleme bei der Auswahl eines Dokumentationsformats:

  1. Ist es einfach zu erstellen?
  2. Ist es leicht zu pflegen?
  3. Ist es einfach zu pflegen, wenn jemand anderes es geschrieben hat?
  4. Kann es ohne großen Aufwand in andere Formate exportiert / konvertiert werden?

1-3 erleichtern mir das Leben und sind wichtig, um schnell Dokumente zu erstellen, ohne wahnsinnig zu werden. Ich denke, die vierte ist die wichtigste auf Kundenseite, da sich die Formate ständig ändern werden. Das Microsoft Word 2003-Format wird es nicht für immer geben, und unsere aktuelle Implementierung von PDF ist es auch nicht. Ich muss sicherstellen, dass alle unsere Kunden unsere Dokumente lesen können, unabhängig davon, welches Betriebssystem oder welcher Dokumentenleser sie ausgewählt haben.

andrewd18
quelle
1

Wir verwenden MediaWiki mit verschiedenen Plugins, einschließlich SemanticMediaWiki. SMW ist nett, weil es unsere MediaWiki-Installation in eine große relationale Freiform-Datenbank verwandelt, die nach Belieben abgefragt werden kann. Möchten Sie wissen, auf welchem ​​Server sich eine Website befindet? Besuchen Sie die Seite. Möchten Sie wissen, welche Websites auf einem Server gehostet werden? Führen Sie eine Abfrage aus, und die Seitennamen werden basierend auf dem richtigen Tag auf der Seite jeder Website ausgewählt.

Karl Katzke
quelle
1

Ich werde nicht mit einem Dokumentationssystem antworten, das ich verwendet habe, sondern mit etwas, das ich gesehen habe und das ich sehr gut finde: http://stackexchange.com/

Bei stackexchange handelt es sich um die Q & A-Plattform, die unter Serverfehlern ausgeführt wird (technisch gesehen ist es nicht genau dasselbe, aber für unseren Zweck können wir hier davon ausgehen, dass es dasselbe ist).

Fogbugz benutzt es .

Es gibt einen interessanten Blog-Beitrag von einem Fogbugz-Mitarbeiter, in dem ich folgende Zitate gefunden habe:

Für alle Zwecke außerhalb der Produktspezifikationen, denke ich, wurden Firmen-Wikis und Diskussionsformen mit einem fatalen Schlag belegt.

...

Seitdem wir FogBugz.StackExchange.com als unsere Support-Plattform verwenden, habe ich dieselbe Frage noch nie zweimal beantwortet. Wir haben sogar einen internen SE-Server, den wir für nicht öffentliche Fragen und Antworten verwenden, und dort gelten dieselben Grundsätze.

Sie verwenden stackexchange für kundenseitige Wissensdatenbank und interne Wissensdatenbank.

Ich bin gespannt, ob solche Wissensaustausch-Q & A-Plattformen Unternehmenswikis ersetzen.

Steven
quelle
0

Bei meinem früheren Arbeitgeber habe ich Word-, Excel- und Visio-Dateien verwendet, die in einem Ordner gesammelt wurden. Eine Hardcopy von allem wurde in einem Ordner in meinem Schreibtisch aufbewahrt. Ich war die einzige IT-Person, so dass kaum jemand auf die Informationen zugreifen konnte.

Bei meinem derzeitigen Arbeitgeber verwenden wir Macola ES von Exact Software. Ich bevorzuge es jedoch, meine Dokumentation in Word zu schreiben und als Anhang in Macola hochzuladen, als den integrierten Dokumenteditor zu verwenden.

Scott
quelle
0

An meinem Arbeitsplatz habe ich ScrewTurn Wiki auf einem unserer Windows-Entwickler-Server abgelegt und an unseren SQL Server angeschlossen. Es funktioniert sehr gut, läuft schnell und steht uns bei der Dokumentation hauptsächlich aus dem Weg. In den zwei Wochen seit seiner Bereitstellung haben wir bereits etwa 60 Seiten mit Informationen hinzugefügt, die nur für unser Team (~ 10 Personen) bestimmt sind.

Bisher behalten wir dort Informationen zu aktuellen und früheren Projekten bei und haben begonnen, Informationen zu den Anwendungen hinzuzufügen, z.

Eine meiner Lieblingsseiten im Wiki war die Seite mit Tools und Bibliotheken. Dort haben wir begonnen, Informationen über unsere bevorzugten Produktivitätswerkzeuge und Bibliotheken hinzuzufügen, die wir häufig verwenden. Ein Beispiel hierfür ist grepWin für die Textsuche in Windows.

Ich würde Ihnen wärmstens empfehlen, sich die gesamte Palette der verfügbaren Wikis anzuschauen und eines zu finden, das zu Ihrer beabsichtigten Verwendung, Funktionalität und Einsatzumgebung passt. Ich entschied mich für ScrewTurn, weil es einfach zu bedienen ist und wir auf unserem lokalen WinServer eine Menge freien Speicherplatz hatten, aber YMMV.

MattGWagner
quelle
0

In einigen Fällen verwenden wir Confluence als Wiki und Sharepoint für Dokumente. Ich glaube, dass das Online-Wiki-Format bevorzugt wird, wenn Sie diese Informationen wirklich umfassend teilen müssen und was viel wichtiger ist, wenn Dokumente sehr oft bearbeitet und aktualisiert werden. Daher denke ich, dass es in den Knowledge Base-Artikeln besser ist, sie ins Wiki zu stellen.

Leonid Shirmanov
quelle
0

Wir verschieben derzeit unsere Informationen aus verschiedenen Dokumenten, die im Netzwerk verteilt sind, an zwei Speicherorte:

  1. Ein Wiki in unserem Intranet
  2. Eine Kopie der Informationen, die sich auf einen bestimmten Server in diesem Server- / Stammverzeichnis beziehen.

Für Netzwerkdiagramme Netzwerk-Editor .

Denken Sie auch daran, während Sie das Was aufzeichnen, aufzuzeichnen, warum etwas so konfiguriert ist, wie es ist. Dies hilft zu verhindern, dass Ideen, die wie eine gute Idee erscheinen, in Fehler verwandelt werden.

David
quelle
0

Wir haben festgestellt, dass MediaWiki ein langsamer Einstieg ist, aber sobald Leute außerhalb der IT erfahren, wie einfach es ist, Kommentare, Änderungen, Bearbeitungen usw. hinzuzufügen, ist es nicht mehr wegzudenken. Entwickler verwenden es für die interne Dokumentation, Abteilung Einrichtungen. Es ist nicht nur ein IT-Dokumentationswerkzeug.

bren
quelle