Sind Wikis wirklich geeignet, um Dokumente für die Softwareentwicklung zu speichern? [geschlossen]

18

Jeder weiß, dass eine gut dokumentierte Softwareentwicklung zum Erfolg führt. In der Regel bedeutet dies jedoch, dass nicht nur einfacher Text, sondern auch binärer Inhalt in das Dokument einbezogen wird, z. B. ein UML-Diagramm. Und ich habe viele Leute das sagen hören. Das Versionskontrollsystem ist nicht der geeignete Ort für die Binärdateien. Ich verstehe das Problem vollkommen und stimme ihm zu. Ich fragte mehrere erfahrene Entwickler, wo sich der beste Ort zum Speichern von Dokumenten befinden sollte, und die Antwort lautete "Wiki". Wiki ist gut, aber ich habe ein weiteres potenzielles Problem in Betracht gezogen. Wie kann der in einem Versionskontrollsystem gespeicherte Quellcode mit dem zugehörigen Dokument im Wiki verbunden werden? Nehmen wir an, jemand klont das Repository von Git oder Quecksilber. Wie kann er / sie das Dokument leicht finden? Oder habe ich gerade etwas verpasst?

Ich weiß, dass einige Wiki-Systeme in Versionsverwaltungssysteme integriert werden können. Aber es geht mir nicht um die Integrationsfähigkeit. Wenn Sie Quellcode aus einem Git-Repository geklont haben und nach einer Weile in einen Zug einsteigen und offline im Zug weiterarbeiten möchten (was ein großes Merkmal von DVCS ist). Dann stellen Sie plötzlich fest, dass Sie keinen Zugriff auf Dokumente haben, da Sie offline im Zug arbeiten. Wenn das Dokument hingegen im Git-Repository gespeichert ist, haben Sie Zugriff auf das Dokument, wenn das Repository geklont ist.

Edison Chuang
quelle
3
Zu Ihrer Information: Wiki ist kein Akronym, es ist ein hawaiianisches Wort, das "schnell" bedeutet.
Jörg W Mittag
Die Tatsache, dass es sich bei der Dokumentation um Binärdateien handelt, ist kein guter Grund, die Speicherung in Ihrem Versionskontrollsystem zu vermeiden. VCSs können problemlos mit Binärdateien umgehen. Wenn Sie es im VCS Ihres Projekts speichern, haben Sie den Vorteil, dass Sie Ihre Dokumentation beim Verzweigen Ihres Projekts verzweigen können.
JW01
Offline-Arbeiten: Die Brute-Force-Lösung besteht darin, die gewünschten Seiten mit einem Offline-Reader herunterzuladen. Eleganter ist es, das gesamte Wiki zu klonen, wenn dies sinnvoll ist (z. B. die zugrunde liegende Datenbank kopieren und eine eigene Installation des Wikis haben). VCS-basierte Wikis sind eine noch elegantere Lösung. Ich arbeite oft offline und in der Regel reicht es aus, nur die Seiten herunterzuladen, die ich regelmäßig benötige.
Sleske

Antworten:

16

Ist WIKI wirklich geeignet, um Dokumente für die Softwareentwicklung zu speichern?

Warum nutzen Sie nicht das volle Potenzial des WIKI als Werkzeug für die Zusammenarbeit, anstatt Dokumente, PDFs und andere Arten von Dateien zu schreiben? Sie können Ihre Dokumente dort schreiben, Ihre Diagramme anhängen und noch besser: Wenn Sie Fitnesse verwenden , können Sie Ihre Wiki-Seiten in wirklich nützliche und lebendige Dokumentation verwandeln, da sie zu einer ausführbaren Spezifikation werden können.

Jeder weiß, dass eine gut dokumentierte Softwareentwicklung zum Erfolg führt

Pass auf diesen auf. Dokumente WERDEN NICHT ZUM ERFOLG FÜHREN, da sie Mistcode nicht in einen guten verwandeln. Dokumente sind jedoch ein Teil des Weges zu einer erfolgreichen Software. Aber nur ein Teil und sie werden gute Praktiken und gute Leute nicht ersetzen.

Fernando
quelle
8

Da mehrere Antworten auf Trac als Vorschlag verweisen, möchte ich eine ähnliche, meiner Meinung nach aber bessere Alternative vorschlagen: Redmine .

Redmine ist eine Projektmanagementlösung, die die Integration von Wiki, Document Repository und Versionskontrolle umfasst. Es ist auch in Ruby on Rails geschrieben und meiner Erfahrung nach viel einfacher zu erweitern und zu hacken als Trac.

Mehr als alles andere ist es sehr einfach zu bedienen und es ist einfach, das Team dazu zu bringen, es zu benutzen.

Eigenschaften:

  • Unterstützung mehrerer Projekte
  • Flexible rollenbasierte Zugriffskontrolle
  • Flexibles Issue Tracking System
  • Balkendiagramm und Kalender
  • Verwaltung von Nachrichten, Dokumenten und Dateien
  • Feeds & E-Mail-Benachrichtigungen
  • Pro Projekt-Wiki
  • Pro Projektforen
  • Zeiterfassung
  • Benutzerdefinierte Felder für Probleme, Zeiteinträge, Projekte und Benutzer
  • SCM-Integration (SVN, CVS, Git, Mercurial, Bazaar und Darcs)
  • Problemerstellung per E-Mail
  • Unterstützung für die mehrfache LDAP-Authentifizierung
  • Selbstregistrierungsunterstützung für Benutzer
  • Mehrsprachige Unterstützung
  • Unterstützung für mehrere Datenbanken

Wenn Sie offline arbeiten, gefällt mir die Idee, die Versionskontrolle mit Designdokumenten zu überfrachten, nicht. Ich bin mir sicher, dass Sie Ihre Gründe dafür haben, aber wie oft sind Sie wirklich offline und benötigen Zugriff auf Designdokumente? Die Chancen stehen gut, dass dies wirklich ein Eckfall ist.

Vitor Py
quelle
+1 Ich benutze Redmine bei der Arbeit und es ist wirklich ein tolles System.
Luiz Damim
5

Einige Wikis (zB Ikiwiki ) haben die Möglichkeit, ihre Daten in Git zu speichern, wie Sie bereits erwähnt haben. Vorausgesetzt, Sie können die Dokumentation als Git-Submodul unter Ihrem regulären Quell-Repository verknüpfen .

Mit dem obigen Setup würde beim Abrufen der Quelle und Aktualisieren der Submodule die neueste Kopie der Dokumentation abgerufen. Offline können Sie jeden nach Belieben bearbeiten. Wenn Sie zu einem Netzwerk zurückkehren, können beide an den von Ihnen verwendeten freigegebenen Speicherort verschoben werden.

Der heikle Teil davon ist, dass Sie bei jeder Aktualisierung der Dokumentation (auch über die Ikiwiki-Weboberfläche) auch das entsprechende Submodul im Git-Quell-Repository aktualisieren müssen. Dies könnte jedoch leicht automatisiert werden.

Greg Hewgill
quelle
Interessant. Gibt es einen Unterschied zwischen dem Ablegen des Dokuments im Git-Repository und dem Speichern des Dokuments über WikiWiki?
Edison Chuang
1
@ Edison Chuang: Nein, gibt es nicht. Wenn Sie einen Klon eines Wiki-Repositorys haben, können Sie die Seiten mit dem Texteditor Ihrer Wahl bearbeiten (Sie müssen kein beschissenes browserbasiertes Texteingabefeld verwenden). Sie können sogar verschiedene Zweige des Wikis verwenden, um eine Momentaufnahme der älteren Dokumentation oder was auch immer zu erstellen.
Greg Hewgill
Es hört sich so an, als ob das Dokument problemlos im Versionskontrollsystem gespeichert werden kann, obwohl die Binärdateien vorhanden sind. Entwickler können nur Tools wie WikiWiki verwenden, um Wiki-Seiten bei Bedarf in HTML-Seiten zu konvertieren.
Edison Chuang
+1 für die Ikiwiki-Wiki-Engine; Die Hatta-Wiki-Engine ist eine ähnliche Idee für Mercurial-Repositories.
David Cary
ISTR Fitnesse speichert seine Wiki-Seiten auch als Textdateien, sodass sie auf Wunsch auch in Ihrem Versionskontrollsystem gespeichert werden können. Während es hauptsächlich zum Testen dient, gibt es keinen Grund, es nicht auch als allgemeines Wiki-System für Ihre Dokumentation zu verwenden.
Jules
4

Es ist sinnvoll, die Dokumentation im selben Repository wie den Quellcode zu speichern. Sphinx scheint mir eine gute Option zu sein.

Brecht Machiels
quelle
2

Trac bietet eine Schnittstelle zu Subversion, ein integriertes Wiki und komfortable Berichtsfunktionen. http://trac.edgewall.org/
Aber ich weiß nichts über Ihren installierten Stack.

Chiron
quelle
Und eine schöne Schnittstelle zu Mercurial. Und es ist hervorragend hackbar.
Frank Shearar
0

Ich würde nicht versuchen, mich an die Offline-Arbeit anzupassen. Ich würde die Ressource verwenden, mit der es am einfachsten ist, für alle zu arbeiten. Wenn Sie beispielsweise PHP-Code schreiben, empfehle ich die Verwendung einer Inline-Dokumentation, die von PHPDocumentor generiert werden kann . Es kann überall generiert werden und es gibt ein Plugin für Trac . Online oder offline haben Sie dann auch relativ schnell Zugriff auf die Dokumentation.

Der Schlüssel liegt in der Benutzerfreundlichkeit. Wenn es schwierig ist zu warten, wird es anfangen zu leiden. Wenn es zu leiden beginnt, sinkt die Dokumentationsqualität. Wenn das passiert, beschweren sich die Leute und dann geht alles bergab.

Chuck Burgess
quelle
-1

Das Speichern von Dokumentation in einem Wiki ist für mich sehr sinnvoll.

Veracity ist ein Beispiel für ein DVCS, das eine engere Integration von Wiki-Inhalten und Quellcode ermöglicht.

Jace Browning
quelle