Welche Art von technischem Online-Dokumentationssystem würden Sie empfehlen? [geschlossen]

11

Ziel ist ein Online-Dokumentationssystem mit folgenden Hauptanforderungen:

  • wird hauptsächlich als Zwischenstufe für die endgültigen technischen Dokumente aller unserer Anwendungen verwendet (die wahrscheinlich jedoch nie fertiggestellt werden:]). Es wird normalerweise so verwendet: Jemand hat ein Problem, ich behebe es und schreibe das Problem sofort auf. Was jetzt passiert, wird unüberschaubar: Jemand hat ein Problem, ich behebe es, sowohl ich als auch jemand sind glücklich, aber 2 Monate später hat jemand anderes das gleiche Problem und niemand erinnert sich, was das Problem war.
  • Zugriff von überall, läuft hinter unserem Apache-Server
  • Benutzer- / Gruppenverwaltung, die schreibgeschützten / schreibgeschützten / Administratorzugriff ermöglicht
  • Das Format ist nicht allzu wichtig: Klartext würde reichen, Wiki-Stil wäre allerdings schöner
  • billig oder kostenlos

einige Ideen von mir:

  • Servieren Sie einfach Dateien auf einer Dateifreigabe oder über SSH (Nachteile: Nicht zu kopierbar mit Windows, Vorteile: Einfach, kann ein beliebiger Dateityp sein)
  • Bewahren Sie es in einem SCM auf (svn / git, idem wie oben, aber einfacher zugänglich und kontrollierbar)
  • Confluence: Wir verwenden Jira bereits. Lohnt sich Confluence? Wie lässt es sich in Jira integrieren?
  • etwas anderes?

Bitte zögern Sie nicht, diese zu kommentieren oder Ihre Erfahrungen mit anderen Systemen zu teilen.

documentation stijn
quelle
Wird die Dokumentation aus Code (z. B. Javadocs) generiert oder wird sie von Grund auf neu geschrieben, als Benutzerhandbuch oder als Kombination aus beiden?
FrustratedWithFormsDesigner
Es handelt sich hauptsächlich um eine Bedienungsanleitung, nicht um eine Codedokumentation (nun, wir haben auch diese, die von Sauerstoff generiert wurde, wir könnten sie einschließen, aber es ist nicht der erste Punkt von Interesse)
stijn
Ich würde Spolsky etwas Geld geben.
Job

Antworten:

11

Ich wollte ein Wiki vorschlagen

Da Confluence ein Wiki ist, halte ich es für eine hervorragende Idee, es mit Ihrem JIRA zu verwenden. Sie haben den Vorteil, dass Sie direkt auf JIRA-Probleme und damit auf den tatsächlichen Code / das Dokument / die vorgenommenen Änderungen usw. zurückgreifen können.

Der Schlüssel zu einem solchen Code-Doc-Repo ist der Navigationsaspekt. Sie möchten keine Seiten, die nicht verbunden, schwer zu finden usw. sind. Denken Sie an ein "Site-Layout", ähnlich wie Sie es für eine Website tun würden.

Martijn Verburg
quelle
Confluence kann anscheinend in verschiedenen flachen Formaten exportiert werden. Klingt nach einer der einfachsten Möglichkeiten, von einem leicht bearbeitbaren zu einem fertigen Produkt zu gelangen
2
Wir haben Confluence, wo ich arbeite - wir sind von MediaWiki migriert - und es leistet gute Arbeit bei der Ausgabe in eine Reihe von Formaten (Word ist das beliebteste). Aber seien Sie gewarnt, die WYSIWYG-Bearbeitungstools sind unglaublich fehlerhaft und das Tagging-System lässt zumindest bei unserer Installation zu wünschen übrig.
Philip Regan
+1 für Wiki fand ich Trac auch in diesem Fall sehr nützlich, da es in SVN integriert ist und auch die gemeinsame Nutzung von Dateien ermöglicht.
Wir haben eine Confluence-Studie überprüft, und es wird die Lösung sein. Scheint viel mehr zu können, als wir brauchen, aber es ist ziemlich einfach, damit zu arbeiten. Ich habe Trac vor ein paar Jahren ausprobiert und es war etwas zu chaotisch für meinen Geschmack, besonders wenn es um Plugins usw. ging
am