Dokumentation und Versionskontrolle

Es hängt wirklich von Ihrem Team ab. Wo ich arbeite, bewahren wir die Dokumentation in einem Wiki auf, das mit unserer Team-Website verlinkt ist. Zum Zweck der Versanddokumentation kann das Wiki exportiert werden und wir führen es durch einen Parser, der das Aussehen der Dokumentation zu Kundenzwecken "fächert".

Das Speichern der Dokumentation mit dem Code (normalerweise in Ihrem Quell-Repository) ist keine schlechte Idee. Stellen Sie nur sicher, dass sie getrennt bleiben. Beispiel: Behalten Sie einen Ordner docs bei, der sich auf der gleichen Ebene mit Ihrem Ordner src in Ihrem Repository befindet. Auf diese Weise können Sie die aktuelle Dokumentation schnell versenden, Sie können Revisionen einfach verfolgen und jeder, der neu im Projekt ist, kann sofort einspringen, ohne zu mehreren Orten gehen zu müssen, um Informationen zu erhalten.

Das Speichern in der Quellcodeverwaltung ist in Ordnung.

Das ist eine interessante Frage - was andere sagen, stimmt mit generierten Dokumentationen, Quelldateien und Vorlagen / etc. sollte in der Quellcodeverwaltung gespeichert und während des Erstellungsprozesses generiert werden.

Soweit Anforderungen / Spezifikationen / etc. Dokumentation, habe ich in beide Richtungen gearbeitet, und ich bevorzuge sehr häufig SharePoint oder ein Wiki / Dokument-Portal, das für die gemeinsame Nutzung von Dokumenten / Versionierung konzipiert ist. Der Grund dafür ist, dass die meisten Nichtentwickler nicht mit Quellcodeverwaltungssystemen arbeiten können, und Sie profitieren nicht von den Vorteilen einer intelligenten Zusammenführung, wenn Sie ein Binärformat wie Word verwenden. Außerdem ist es nett, einen internetbasierten Zugriff zu haben, so dass Sie in einem verteilten Team auf die Dokumente verweisen und daran arbeiten können, ohne dass zusätzliche Software installiert werden muss.

Wenn Sie mit jeder Version des Produkts eine versionierte Benutzerdokumentation erstellen, ist es sinnvoll, die Dokumentation zusammen mit der zugehörigen Produktversion in die Quellcodeverwaltung zu übernehmen.

Wenn Sie interne Entwicklerdokumentation schreiben, verwenden Sie die Dokumentation des internen internen Quellcodes (javadoc, doxygen, .net-Annotationen usw.) für Quelldokumentationen und ein Projekt-Wiki für die Dokumentation auf Konstruktionsebene.

Ich denke, die meisten von uns in der Branche befolgen die Best Practices nicht wirklich und hängen natürlich auch sehr von Ihrer Situation ab.

In einer agilen Umgebung, in der Sie einen sehr iterativen Prozess der Veröffentlichung haben würden, möchten Sie "leicht reisen". In diesem speziellen Fall funktioniert Jasons Vorschlag eines separaten Wikis wirklich großartig.

In einem Wasserfall- / Urknall-Modell haben Sie mit jeder neuen Version eine bessere Gelegenheit, ein anständiges Dokumentations-Update zu erhalten. Außerdem müssen Sie klar dokumentieren, welche Version der Anforderungen vereinbart wurde, und Sie haben eine Menge Dokumentation für jede kleine Änderung, die Sie an den Anforderungen vornehmen (aufgrund der Auswirkungen auf nachfolgende Phasen). Wenn die Dokumentation mit dem versionsgesteuerten Quellcode zusammen leben kann, ist es oft das Beste.

Hier ist eine Zusammenfassung der Optionen und meiner Erfahrung für 2017:

• Ganz extern (z. B. ein Wiki) - die Leute kümmern sich nicht darum, sie auf dem neuesten Stand zu halten (die Hälfte von ihnen weiß nicht einmal, wo sie die Seite finden, die aktualisiert werden muss) der Schützengräben).
• Vollständig intern (z. B. Javadoc) - verschmutzt den Quellcode und ist normalerweise zu niedrig, um von Nutzen zu sein. Gut geschriebener Quellcode ist immer noch die beste Form der Low-Level-Dokumentation.
  • Ich glaube, package-info.java Dateien sind nicht ausgelastet.
• Colocated -Dokumentation (z. B. README.md ) - Eine gute halbwegs Lösung mit den Vorteilen der Versionskontrolle. Wenn eine einzelne Datei nicht ausreicht, betrachten Sie einen doc/ -Ordner. Der einzige Nachteil, den ich gesehen habe, ist, ob man hilfreiche Grafiken (z. B. png files) von der Steuerung bezieht und das Repo aufbläht.
  • Eine interessante Möglichkeit, um dieses Problem zu vermeiden, ist die Verwendung von Klartext-Diagramm-Tools (ich finde Grapheasy ) ein Atemzug von frischer Luft).

Der Erfolg von Github ist nicht zuletzt der README.md zu verdanken, die sich im Wurzelbereich des Projekts befindet.