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:
Antworten:
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:
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.
quelle
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.
quelle
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
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.
quelle
Wir haben kürzlich begonnen, das Alfresco DMS zu verwenden, das viele interessante Eigenschaften hat:
Es gibt auch einige Nachteile:
Wenn Sie es versuchen möchten, teilen Sie mir bitte Ihre Meinung mit.
quelle
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).
quelle
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.
quelle