Program Documentation

[DMD-OS]

hallo alle,

wie dokumentiert man am besten sein programm?
gibt es regeln an die man sich halten sollte?
gibt es ein gutes open-source programm zur erstellung einer documention.
ich hab da noch nicht so den durchblick.
habe mal von dia, star_uml gehört, weiß aber nicht wie man die benutzt und welches wirklich gut ist...
hat da jmd erfahrung?

[__blackjack__]

@DMD-OS: Es wird aus der Frage nicht ganz klar was für Dokumentation es werden soll: für Benutzer oder für Programmierer? Für beides eignet sich Sphinx, das Werkzeug mit dem die Python-Dokumentation erstellt wird, und das auch von den meisten Python-Bibliotheken verwendet wird.

Sphinx wird auch von Projekten verwendet die nicht in Python geschrieben sind, und sogar für Dokumentation/Bücher die allgemeiner sind kann man es verwenden.

Für Benutzerdokumentation kann man ansonsten ziemlich viel verwenden. Die üblichen Textverarbeitungen, LaTeX, DocBook, AsciiDoc, Pandoc, …

[DMD-OS]

@__blackjack__:
am besten für beide arten benutzer und programmierer
hab grad gelesen, daß man mit doxygen eine docu aus dem programmcode erstellen kann.
geht das mit sphinx auch?

[__blackjack__]

@DMD-OS: Jain. Nicht ganz so wie bei Doxygen. Man kann bei Sphinx in den Quelltexten der Dokumentation Docstrings und spezielle Kommentare aus den Modulen in die Dokumentation übernehmen.

[noisefloor]

Hallo,

hab grad gelesen, daß man mit doxygen eine docu aus dem programmcode erstellen kann.

Ja, aber das ist dann halt eher eine API Doku und kein Benutzerhandbuch. Kommt halt drauf an, was du willst.

Ich habe immer wenn ich eine Doku geschrieben habe Sphinx benutzt. Das ist schon ziemlich gut dafür.

BTW: Wenn du eine deutschsprachige Doku schreibst solltest du vorher vielleicht noch an deiner Groß-/Kleinschreibung feilen. Entweder ist dir entfallen, dass es die im Deutschen nun mal gibt - oder deine Umschalt-Taste ist defekt.

Gruß, noisefloor

[DMD-OS]

Ich finde natürlich die englische Sprache besser.
Werde wahrscheinlich nicht die deutsche verwenden.
is doch viel besser, wenn man die umschalttaste einfach rausreisst

[kbr]

Dann bekommst Du irgendwann Schwierigkeiten mit PEP 8

Rechtschreibregeln sind sehr hilfreich, denn sie unterstützen die Lesbarkeit von Texten und deren inhaltliches Verständnis. Manche Beiträge lese ich gar nicht mehr, da ihnen beides abgeht.

[DMD-OS]

in zukunft wird es sowas nicth ma gebe!