Software-Umgebung Dokumentation Checkliste [geschlossen]

Question

Ich arbeite für eine Versicherungsgesellschaft. Wir haben unsere eigene Entwicklungsabteilung hergerichtete von fast 150 Personen plus einige Anbieter (Outsourcing und maßgeschneiderte Anwendungen ziemlich viel). In unserem Unternehmen hat mein Team gemacht, was wir nicht-funktionale Logik Bibliotheken nennen. Das heißt, Software-Bibliotheken Dinge zu behandeln, die alle Entwicklungsteams in unserer Abteilung horizontal sind, z.B. Sicherheit, Webservices, Logging, Messaging und so weiter. Die meisten oder diese Werkzeuge werden entweder von Grund auf oder Anpassung eines de-facto-Standard. Zum Beispiel unsere Logger ist ein appender auf Log4J basiert, die auch die Log-Meldungen in einem DB gespeichert werden. Wir definieren auch, welche Bibliotheken in der Anwendung zu verwenden, zum Beispiel des Rahmen für einen Web Service zu nutzen. Wir verwenden so ziemlich JavaEE und Oracle AS in all unserer Organisation (mit einigen Websphere Application Server).

Ein Großteil dieser Projekte haben ihre Architektur (Use Cases, UML-Diagramme, etc.) dokumentiert und in der Regel die generierte Dokumentation zur Verfügung. Nun, was wir haben, ist zu sehen, dass für die Nutzer manchmal schwierig ist, die die Bibliotheken zu verwenden, wir bieten und die ständig Frage zu stellen oder sie einfach benutzen sie nicht.

So wir eine freundlichere Dokumentation für sie zu generieren planen, so meine Frage ist: Was sind die besten Praktiken oder die Checkliste, die Software-Dokumentation haben sollte?

Etwas kommt mir in den Sinn:

1. API Reference Guide
2. Schnellstart Tutorial
3. API generierte Dokumentation.
4. Müssen durchsuchbar sein
5. Web Access

Was sollte es haben? Auch auf Basis Ihrer Erfahrung, was die beste Art und Weise zu halten ist (es immer up-to-date) und veröffentlichen diese Art der Dokumentation?

Answer 1

Halten Sie Ihre Dokumentation in der Versionskontrolle zu.

Stellen Sie sicher, auf jeder Seite eine Versionsnummer hat, so dass Sie wissen, wo Ihre Benutzer gelesen hat.

Holen Sie sich ein CI-Server gehen und Push-Dokumentation zu einer Live-Dokumentations-Website auf Updates.

Haben Bewertungen Dokumentation wie Sie Bewertungen würden codieren.

Dog-Food-it:)

Güte,

Dan