Softwaredokumentation



  • Hallo,

    wie bzw. mit was erstellt ihr euere Softwaredokumentation?
    Mich würde interessieren, wie soetwas bei euch in der Praxis abläuft. (Es muss ja nicht zwingend überall darauf verzichtet werden)



  • Meinst du Codedoku oder Benutzerhandbücher?



  • Word, sowohl auf rbeit als auch daheim. Auf der Arbeit, weils so vorgegeben ist und wir entsprechende Formatvorlagen benutzen müssen. Daheim, weil ich nicht stundenlangen Aufwand für irgendein anderes System betreiben wollte, das ich installieren und in das ich mich erst wieder einarbeiten müsste. ~40h für die erste Konzeptphase (vor allem Architekturentwurf) reichen auch, bin schließlich Entwickler und kein Schriftsteller 😉



  • Bei .NET schreibe ich XML-Kommentare für den Code und mache mit dem Sandcastle Help File Builder HTMLs oder CHMs draus, je nach dem was man so braucht.
    Und dann Word für das Handbuch, welches mit DocToHelp für diverse Formate aufbereitet wird.



  • Dokumentierende Code-Kommentare in C++ schreibe ich im JavaDoc-Stil und extrahiere sie mit Doxygen. Irgendwann™ wird dann ein Teil davon für die Schnittstellendoku meines Frameworks auch nach außen transportiert, bis dahin bin ich etwas fahrlässig, was die übermäßig ausführliche Doku angeht...



  • Doxygen im Code, Wiki firmenintern, PDF (LO Writer) für Kunden.



  • 7ieben schrieb:

    Meinst du Codedoku oder Benutzerhandbücher?

    Egal, beides ist zulässig, da mich beides interessiert.



  • Code sollte man nur mit Unit-Tests dokumentieren - alles andere wird zu schnell obsolet.



  • Ich denke aus Bequemlichkeit mal so:
    --> Die Dukumentation des Codes gehört weitestgehend in den Code und kann dort erledigt werden. Nur für komplexe Dinge sind weitere Aufzeichnungen sinnvoll.
    --> Für das Benutzerhandbuch reicht jedes Schreibprogramm wie WORD voll aus. Nur welcher Benutzer will das erst oder ständig lesen?
    --> Hilfestellungen für den Benutzer im Programm bereitstellen!
    --> Programm für den Benutzer so schreiben, dass er möglichst ohne langes Lesen der Dokumentation arbeiten kann.
    --> Zur Entscheidung, ob jemand das Programm kaufen will, sind ggfs. zusätzliche Dinge sinnvoll.



  • Benutzerhandbücher gibt es hier nicht. Das Geld was in Handbücher verballert wird, sollte man lieber in einen erfahrenen UX Designer stecken.



  • sss schrieb:

    Code sollte man nur mit Unit-Tests dokumentieren - alles andere wird zu schnell obsolet.

    Dann sitzt man vor dem Test bzw. Testcode und fragt sich, was er testet. Problem erfolgreich verschoben.

    Programm für den Benutzer so schreiben, dass er möglichst ohne langes Lesen der Dokumentation arbeiten kann.

    Ich find 's witzig, wenn man diese Einstellung auf die "wirkliche Welt" uebertraegt. Z.B. bei der Reparatur eines Motors.



  • Ich find 's witzig, wenn man diese Einstellung auf die "wirkliche Welt" uebertraegt. Z.B. bei der Reparatur eines Motors.

    Falsche Analogie.

    Ein Programm ist für den Anwender eher vergleichbar mit einem Auto. Die verwendete Technologie entspricht dem Motor des Autos.



  • Anaolg schrieb:

    Ich find 's witzig, wenn man diese Einstellung auf die "wirkliche Welt" uebertraegt. Z.B. bei der Reparatur eines Motors.

    Falsche Analogie.

    Ein Programm ist für den Anwender eher vergleichbar mit einem Auto. Die verwendete Technologie entspricht dem Motor des Autos.

    ja, wirklich schöne Analorgie



  • Kein noch so gut gestaltetes Benutzerhandbuch - gedruckt, als Hilfesystem, oder online-Dokumentation - kann dem Benutzer geben, was das Programm unverständlich oder zu kompliziert hergibt. Das Stichwort ist 'Software-Ergonomie' und diese gehört notwendig schon in das Design des Programmes. Auch das ist eine wesentliche Aufgabe jeder Softwareentwicklung und erfordert zusätzliche Mühe. Die schönste GUI ist oft nebensächlich!

    Zur Analogie Auto und Motor: Mit dem Auto will man fahren. Der Motor soll zuverlässig dafür seinen Dienst tun, die Bremsen und einiges mehr auch. Funktioniert da etwas nicht, ruft man den Pannendienst oder fährt zu einer Werkstatt. Bei Software wäre der Pannendienst die Hotline des Softwarentwicklers (soweit vorhanden). Die Werkstatt wäre die Programmierung mit einem neuen Update.

    Zur Source-Dokumentation: Diese muss so sein, dass man sich selbst und jeder andere darin später schnell zurecht findet. Unverhofft auftretende Fehler sollten leicht korrigierbar und Wünsche zur Erweiterung der Programmleistungen möglich und idealerweise vorbereitet sein.



  • Das kommt ganz drauf an, was dokumentiert werden muß, und für wem die Doku sein soll.

    Vorzugsweise html, das hat schon einige Vorteile, meist ist auf plattformen schon irgendein Browser zum Lesen vorhanden, Bilder gehen, ausdrucken auch möglich, wenn auch nicht so schön wie pdfs. Html ist online wie offline lesbar, einfach zu erstellen usw.

    Wenn bei Games ein gutes ingame Tut da ist, oder eine PDF, Htmlseite oder gutes Readme oder Worddatei whatever, die auch hilft, das Spiel vernünftig auszuloten, oder inspirierend wirkt, oder zumindest grundlagenmäßig erklärt, dann finde ich das auch sehr gut. Aber viel Spieldoku, wenn man so will, ziehe ich natürlich auch aus Walkthrougs oder Fanseiten. Bei Diablo z.B. die vielen Runenrezepte auszuprobieren, ist z.B. etwas albern, vor allem, weil man einige wichtige High-Level-Runen ja auch nur selten findet. Normalerweise findet man in anderen Spielen Rezeptrollen für dies und das, wäre auch in Diablo eine Option gewesen, die aber auch durch Fansites regelmäßig überflüssig wird.

    In der Realworld gibt es den ein oder anderen Dokuskandal, z.B. weil viele technische Manuals nur für Servicewerkstätten oft besser informieren oder wichtige Infos auch für Benutzer beinhalten. Ähnlich Skandalöses gibt es in der Schule bei Mathematikbüchern, weil Lösungen zu vielen Aufgaben nicht dabei sind oder nur für Lehrer erhältlich.


Log in to reply