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.
quelle
Antworten:
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.
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.
quelle
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:
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.
quelle
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.
quelle
Es ist sinnvoll, die Dokumentation im selben Repository wie den Quellcode zu speichern. Sphinx scheint mir eine gute Option zu sein.
quelle
Trac bietet eine Schnittstelle zu Subversion, ein integriertes Wiki und komfortable Berichtsfunktionen. http://trac.edgewall.org/
Aber ich weiß nichts über Ihren installierten Stack.
quelle
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.
quelle
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.
quelle