Eure favorisierte Form der Dokumentation

[Valle]

Wir verwenden Python, daher bin ich hier vielleicht etwas außenvor.

Python unterstützt Dokumentation als Teil der Sprache. Packages, Klassen und Methoden können jeweils mit einem String beginnen, der die Dokumentation beinhaltet. Es existieren entsprechende Tools um das dann in beliebige andere Dateiformate umzuwandeln. Bei uns klappt das eigentlich ganz gut.

Hier mal ein Beispiel, für die, die sowas noch nicht gesehen haben:

Code:

"""
My Module

>>> inline_code_example()
"""
 
class Foo:
    """
    My Class
    """
 
    def __init__(self):
        """
        My Constructor
        """
        pass
 
    def add(self, a, b):
        """
        Returns ``a`` + ``b``
        """
        return a + b

[bernau]

Zur Dokumentation des Quellcodes habe ich ja schon etwas geschrieben.

Dokumentation ist aber ein weit gefächtertes Thema. Zur Dokumentation gehört auch Pflichtenheft, Bedienungsanleitung, etc.

Mit Word-Dateien konnte ich nie wirklich etwas anfangen. Zumal die Arbeit immer an einer Person hängen bleibt.

Wir sind bei diesen Bereichen nun auf ein WIKI umgeschwengt. Zwar bleibt die Doku weiterhin die Aufgabe von 1-2 Personen. Aber Korrekturen (z.B. für die Rechtschreibung und Formulierung) können auf viele Personen aufgeteilt werden. Die Verwaltung des Dokumentes ist zentral. Es gibt keine verschiedenen Versionen. Bei Fragen kann man direkt auf den entsprechenden Link verweisen. Änderungen in der Doku sind leicht auffindbar.

Gute Erfahrung habe ich mit DokuWiki gemacht.

[p80286]

[/OT]
Dokumentation?

Die Form ist mir inzwischen ....egal. Aber stimmen muß sie. Oft genug steht da drin, was man gerne hätte, aber nicht was man programmiert hat.
(Sonst gäb es z.B. keine abweichenden Feldnamen)

Gruß
K-H

[/OT]