Software zur Organisation und Pflege der Projektdokumentation, Spezifikation? [geschlossen]

15

Ich bin auf der Suche nach Software zum Organisieren und Verwalten der projektinternen Dokumentation, Spezifikation, Anforderungen usw. Zur Zeit speichern wir die gesamte Dokumentation als viele MS Word DOC-Dateien in einem Quellcodeverwaltungs-Repository, mit dem wir die Versionskontrolle durchführen können. Sie können diese Informationen jedoch nicht durchsuchen, keine Verknüpfungen zwischen ihnen erstellen, keine Kategorien erstellen und keine Zusammenarbeit durchführen.

Anforderungen, Vorlieben:

  • Keine Installation auf Client-Seite (WEB-basiert).
  • Versionskontrolle von Dokumenten.
  • Dokumentanmerkungen.
  • Dokumentverknüpfung.
  • Vollständige Suche (alle Unterlagen).
  • MS Word (* .doc) Import / Export.
  • WYSIWYG-Texteditor.

Systeme, die ich bisher entdeckt und ausprobiert habe:

Alex Burtsev
quelle
Welche Art von Projektdokumentation haben Sie (Text-, Grafik-, UML-Diagramme, Zeitpläne, Textspezifikationen, User Stories usw.)? Wie viele Leute müssen es warten? Muss es mit bestimmten Versionen / Revisionen Ihres Quellcodes synchron sein?
Doc Brown
@DocBrown, 95% Text, 3-5 Personen werden es schreiben. Ich bin mit den Versionen der Softwareprodukte synchronisiert, aber nicht mit den Quellcode-Revisionen.
Alex Burtsev
XWiki sieht aus wie eine schöne Lösung. Es ist kostenlos und lässt sich gut in MS Office integrieren.
Alex Burtsev
1
Dies ist fast ein Duplikat von Welches Programm verwenden Sie, um technische Dokumentation zu schreiben? und viele der Antworten sind ähnlich, aber es gibt bessere Argumente gegen die Verwendung eines Wikis für eine solche Dokumentation.
Mark Booth
Wie wäre es mit einer Wissensmanagement-Software wie PHPKB ? Es ist nicht kostenlos, aber es scheint Ihrem Zweck sehr gut zu dienen.
Anirudh Srivastava

Antworten:

6

Wie wäre es mit so etwas wie Sphinx ?

Sie schreiben Ihre Dokumentation in reStructuredText (die Syntax ähnelt Markdown, das von Stack Overflow verwendet wird) in reine Textdateien (= einfache Versionskontrolle) und Sphinx spuckt HTML-Seiten aus.

Die beiden bekanntesten Sphinx-Benutzer sind die Python-Sprache und TortoiseHG (siehe die Links für die von Sphinx generierte Dokumentation).


BEARBEITEN:

Ich habe gerade gelesen, dass es sich um projektinterne Dokumentation handelt, nicht um Endbenutzerdokumentation.
Meiner Meinung nach ist so etwas wie Sphinx auch der beste Weg für die interne Dokumentation (vorausgesetzt, Sie können Ihre Analysten dazu bringen, reStructuredText zu schreiben), weil:

  1. Sie können die Dokumente problemlos versionieren (und Unterschiede bei Textdateien benötigen viel, viel weniger Platz als Binärdateien wie .doc oder .pdf).
  2. Wenn ein Entwickler eine gut lesbare .doc- oder .pdf-Datei haben möchte, kann er sie mit Sphinx aus den Quellen erstellen.

Wenn Sphinx zu kompliziert ist, gibt es noch einen einfacheren Weg: Sie können Ihre Dokumentation in Markdown schreiben und mit Pandoc (zum Beispiel) .rtf-, .doc- oder .pdf-Dateien erstellen (dies kann viel mehr).
Ich fand Pandoc einfacher als Sphinx, aber Pandoc kann keine netten Menühierarchien wie Sphinx erstellen (wie in der Python- und TortoiseHG-Dokumentation, die ich oben verlinkt habe).

Unabhängig davon, welches der von Ihnen verwendeten Tools Sie verwenden, können Sie einen internen Webserver und einen Buildserver so einrichten, dass der Buildserver eine HTML-Ausgabe generiert und diese jedes Mal auf den Webserver kopiert, wenn jemand etwas in die Dokumentation überträgt. Damit Ihre Analysten nicht einmal über die endgültige Ausgabe nachdenken müssen, müssen sie nur ihre Änderungen festschreiben und vorantreiben.

Christian Specht
quelle
Sieht so aus, als würde nur HTML generiert, dann muss ich es auf einem Webserver veröffentlichen
Alex Burtsev,
1
@AlexBurtsev: Wenn Sie möchten, dass es öffentlich ist, dann ja. Andererseits verwenden Sie jetzt Word-DOC-Dateien. Sie müssen diese also auch auf einem Webserver ablegen, wenn Sie möchten, dass sie öffentlich sind.
Christian Specht
Ich stelle fest, dass Sphinx einen Pfad "Ausgabe in PDF" hat.
Robert Harvey
@ChristianSpecht, Wiki und Wordpress haben Plugins zum Importieren von Word Doc-Dateien.
Alex Burtsev
@AlexBurtsev: Ich bin nicht sicher, ob ich verstanden habe, was Sie mit der Dokumentation machen wollen. Wenn Sie es ins Internet stellen möchten, benötigen Sie eine Art Webserver, egal ob Sie Sphinx, Wordpress, einen .doc-Download oder etwas anderes verwenden. Wenn Sie die Dokumentation mit Shrink-Wrap-Software verteilen müssen, können Sie mit Sphinx PDF- oder Windows-Hilfedateien erstellen.
Christian Specht
5

Nun, Sie können versuchen, ein Wiki zu implementieren. Mediawiki enthält alle fehlenden Funktionen, von denen Sie sprechen (Suchfunktionen, Versionsverlauf, Links, Kategorisierung). Sie müssen sicherstellen, dass Sie genau wissen, welche Version der Dokumentation zu welcher Version der Software gehört. Dies kann jedoch auch durch Angabe einer Versionsreferenz oder einer bestimmten Kategorie in jedem versionsabhängigen Artikel erfolgen.

ABER: Sie schreiben, Sie haben "Analysten", die keine Entwickler sind (ich gebe zu, ich bin kein Fan dieser Konstellation). Diese Art von Menschen sind oft nicht glücklich, wenn Sie ihre MS Office-Tools durch ein textorientiertes Tool wie ein Wiki ersetzen. Und da MS-Word keine freie Software ist, schätze ich, dass die Anforderung "freie Software" nicht wirklich ein Muss ist. In dieser Situation ist ein Sharepoint-Server möglicherweise die bessere Alternative. Nicht kostenlos, aber AFAIK bietet alle Funktionen, die Sie anfordern, und Dokumente können weiterhin mit Word, Excel usw. erstellt werden.

Doc Brown
quelle
1
Wir haben bereits einen SharePoint-Server, aber Entwickler mögen ihn nicht und möchten ihn nicht verwenden (ich bin selbst Entwickler). Wir wollen etwas, wo wir leicht Informationen finden können, die wir brauchen. Informationen, die kategorisiert und verknüpft sind.
Alex Burtsev
@AlexBurtsev: Ich habe selbst noch nie einen Sharepoint-Server verwendet, aber ich hatte den Eindruck, dass Sharepoint alle von Ihnen beschriebenen Funktionen bereitstellt. Wenn Sie jedoch ein Wiki bevorzugen, ist Mediawiki für Sie in Ordnung. Sie werden jedoch einige anfängliche Anstrengungen unternehmen, um es zu installieren, eine Gliederung der Struktur zu definieren und auch einige Konventionen definieren, wie es verwendet / nicht verwendet werden soll.
Doc Brown
Ich probiere gerade XWiki für seine MS Office-Integration aus
Alex Burtsev
@ DocBrown - SharePoint ist schrecklich. Es ist nicht intuitiv, ein komplettes Labyrinth von Registerkarten und Unterregistern und behält keine ordnungsgemäße Versionskontrolle bei. Jeder, der es verwendet, sollte alle seine Dokumente in einem freigegebenen Verzeichnis auf einem internen Server ablegen. Ein Wiki ist normalerweise der richtige Weg für solche Dinge.
Polynom
2

Es ist immer besser, die Spezifikation und Dokumentation unter Versionskontrolle zu halten, da dies den größten Einfluss hat, obwohl die Lernkurve etwas steiler wäre. Im Falle einer Wissensmaschine empfehle ich Folgendes

  1. Trac - Einfach zu verwendendes Bug-Tracking-System und Wissens-Engine. In Python geschrieben und erweiterbar, sind Sie in wenigen Minuten einsatzbereit
  2. MoinMoin - Vollwertige Wiki-Engine. Wieder Python mit vielen Funktionen

Beide haben minimale Benutzeroberflächen, unterstützen die meisten Wiki-Strukturen, sind recht einfach bereitzustellen und zu warten, unterstützen Revisionen, haben einen guten WYSIWYG-Editor und Sie können sogar Ihre Dokumentation und Spezifikation behalten. Sofern Ihre Projekte nicht wirklich umfangreich sind, können Sie eine der oben genannten Optionen auswählen.

Übermensch
quelle
2

Wir haben kürzlich begonnen, das Alfresco DMS zu verwenden, das viele interessante Eigenschaften hat:

  • Sehr einfache Installation
  • Verfügt über einen integrierten Indexer zum schnellen Durchsuchen vieler Dokumente
  • Ermöglicht Workflows, Gruppen und ggf. den spezifischen Zugriff auf Dokumente durch Kunden
  • Open Source
  • Aktive Gemeinschaft
  • LDAP / AD / SSO-Integration
  • Verarbeitet viele verschiedene Dokumente

Es gibt auch einige Nachteile:

  • Die Benutzeroberfläche ist nicht immer intuitiv
  • Es ist nicht wirklich ein Wiki, daher ist die gleichzeitige Zusammenarbeit an einem Dokument möglicherweise etwas fragil

Wenn Sie es versuchen möchten, teilen Sie mir bitte Ihre Meinung mit.

Dibbeke
quelle
0

Eine andere Möglichkeit könnte sein, LaTeX oder einen anderen Textformatierer (vielleicht texinfo oder sogar lout ) für die Dokumentation zu verwenden. Teile davon können maschinell erzeugt werden. Es gibt einige Tools für die HTML-Konvertierung, z. B. HeVeA , um LaTeX in HTML zu konvertieren. Sie können doxygen auch verwenden , um Dokumentation aus strukturierten Kommentaren in Ihrem Quellcode zu generieren. Und die handgeschriebenen Teile der Dokumentation können (und sollten) als Quellcode verwaltet werden (zB Versionskontrolle und Build).

Basile Starynkevitch
quelle
Ich spreche nicht über Software-Produktdokumentation (Hilfe, Handbuch). Ich spreche von Software-Spezifikation, Geschäftsanforderungen.
Alex Burtsev
Sie können Software-Spezifikationen oder technische Dokumente in LaTeX schreiben, und in einigen Kreisen ist dies üblich.
Basile Starynkevitch
2
LaText erinnert mich irgendwie an * NIX, und unsere Analysten haben noch nie von einem solchen Betriebssystem gesprochen -), sie leben in der Windows-Welt und werden sich nicht auf etwas einigen, das schwieriger ist als Word für die Texteingabe.
Alex Burtsev
-2

Ich würde vorschlagen, zusätzlich zu Ihren Dokumenten ein UML- und ERD-Tool zu verwenden. Sie können diese Dokumente auch in ZOHO bei ZOHO-Docs speichern. Dies ist nicht kostenlos, aber äußerst kostengünstig und ermöglicht die Dokumentensuche.

Unabhängig davon, welches Tool Sie verwenden, müssen Sie den Dokumentinhalt sorgfältig organisieren, um die Textsuche verwenden und aussagekräftige Ergebnisse erzielen zu können. Die Organisation von Dokumenteninhalten in Verbindung mit einer cleveren und einheitlichen Benennung von Dateien kann dabei eine große Hilfe sein.

Keine Chance
quelle