nicht angemeldet
Dokumentation von Softwareprojekten
Hallo, Forumsteilnehmer.
Demnächst steht für ein von meiner Firma programmiertes Softwareprojekt eine Dokumentation an. Jetzt wollte ich fragen, wie "Profis" so etwas anfassen. Mir scheint es momentan so zu sein, dass jeder sein eigenes Süppchen braut und je nach Gusto Word, PDF-Writer, HTML etc. nutzt. Wir möchten im voraus eine zukunftsfähige Lösung nutzen, die Im Prinzip "ALLES" (also sowohl Produkte, als auch Vorgänge in unserer Firma etc.) dokumentieren kann.
Anforderungen sind:
1. Interne und Externe Dokumentation
Wir benötigen
- Benutzerhandbuch (Extern)
- Administrationshandbuch (Intern. enthält z.B. Coding-Rules, etc.)
2. Ursprungsformat kann umgewandelt werden in:
-XML
-HTML
-PDF
-CHM-Dateien
-?
3. Zukunftsfähigkeit
Wenn demnächst die neue Hype-Technologie nach XML erscheint, sollte ich es auch in dieses Format umwandeln können, ohne alles händisch umtragen zu müssen.
Also, wie machen das Profis? Welche Tools gibt es auf dem Markt? Was kosten diese?
Danke für Hilfe und Anregungen jeder Art!
Martin
-
Hallo Martin,
Demnächst steht für ein von meiner Firma programmiertes Softwareprojekt eine Dokumentation an. Jetzt wollte ich fragen, wie "Profis" so etwas anfassen. Mir scheint es momentan so zu sein, dass jeder sein eigenes Süppchen braut und je nach Gusto Word, PDF-Writer, HTML etc. nutzt. Wir möchten im voraus eine zukunftsfähige Lösung nutzen, die Im Prinzip "ALLES" (also sowohl Produkte, als auch Vorgänge in unserer Firma etc.) dokumentieren kann.
Die Tools sind sekundär, wenn das inhaltliche Konzept zur Dokumentation stimmt.
Ein SGML/XML-basierter Standard zur technischen Dokumentation ist DocBook z.B. in Kombination mit einem XML-Editor
Es gibt dazu Standard-XSLT-Stylesheets zur Umwandlung in verschiedene Formate wie HTML, PDF usw.
Gruß
Franz -
Hi Martin,
Demnächst steht für ein von meiner Firma program-
miertes Softwareprojekt eine Dokumentation an.bist Du Dir bewußt, welche Zielgruppe(n) welche Fragen
an diese Dokumentation haben werden?Jetzt wollte ich fragen, wie "Profis" so etwas
anfassen. Mir scheint es momentan so zu sein, dass
jeder sein eigenes Süppchen braut und je nach Gusto
Word, PDF-Writer, HTML etc. nutzt.Ich halte das verwendete Format für sekundär - so etwas
zu konvertieren kann im Zweifelsfalle ein Programm tun.Die Inhalte der Dokumente (Plural ist Absicht) sind
weitaus wichtiger.Wir benötigen
Das ist der Punkt, der mich am meisten interessiert.
Punkt 1: Wo ist die Spezifikation, das allerwichtigste
Dokument überhaupt?- Inhalt: _Was_ kann das Produkt? (nicht _wie_)
- Zielgruppe: Management, Vertrieb, Kunden (nicht User!)
- Benutzerhandbuch (Extern)
Inwiefern ist dies identisch mit der in das Produkt
eingebauten Online-Hilfe? Läßt sich vielleicht sogar
beides aus demselben Quelltext generieren?- Administrationshandbuch (Intern. enthält z.B.
Coding-Rules, etc.)
Beides würde ich nicht in dasselbe Dokument stecken.
Ein Administrationshandbuch sollte zur Administration,
also Bedienung des Produkts dienen.
Da sollten also alle vorhandenen Einstellungsmöglich-
keiten detailliert beschrieben werden - in einem Maße,
das für den Leser des Benutzerhandbuchs zu detailliert
oder uninteressant sein darf. Ein RZ-Mitarbeiter sollte
die Antwort auf alle seine Fragen hier finden. Auch
allgemeine Dinge wie Betriebskonzept, Backup-Konzept
usw. gehören also hier hinein.
Zielgruppe sind Administratoren, Operateure etc.; auch
ein sehr engagierter Anwender sollte das lesen können.Die Programmdokumentation ist dagegen ein Dokument,
das sich ausschließlich an Programmierer wendet.
Hier stehen sowohl Coding-Rules (m. E. weniger wichtig)
als auch der grundsätzliche Aufbau des Programms, ins-
besondere die Modul-Struktur und die APIs der wichtig-
sten Funktionen. Ebenso sind hier grundsätzliche De-
sign-Entscheidungen dokumentiert - "warum wurde das so
und nicht anders implementiert?". Verworfene Alternati-
ven zu dokumentieren ist sehr wichtig.
Es ist nicht unüblich, diese Informationen direkt im
Quelltext des Programms abzulegen (und ggf. via Tools
daraus zu extrahieren, um separate Dokumente daraus zu
erzeugen). Denn wer dieses Dokument lesen kann, der hat
auch mit dem Quelltext zu tun und wird sich freuen,
wenn die Information dort steht, wo er sie braucht
(und ggf. via "grep" etc. finden kann).Viele Grüße
Michael