[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Wie dokumentiert ihr? Suche eleganten Weg für Dokumentation.



Hi,

ich meine damit nicht offizielle Dokumentationen, wie sie in bestimmten 
Projekten gefordert sind. Da ist man zumeist festgelegt. Es geht mir vielmehr 
umd die eigenen kleine Projekte, die hints und tips, die sich mit der Zeit 
ansammeln und die, besonders unter Linux notwendigen, HOWTO's aus eigener 
Erfahrung.

Am Anfang stand und steht auch heute noch oft eine einfache Textdatei. 
Darauf aufbauend habe ich schon mit der einfach pod-Formatierung (perl) 
gearbeitet. Daraus läßt sich HTML und LaTeX herstellen.

Oder ich habe schon direkt mit LaTeX dokumentiert. Ist mit aller der 
Auszeichnerei und Nachschlagerei, wie eine Tabelle jetzt so oder so 
eingegeben werden muß, relativ aufwendig. Aber man kann mit der Doku 
nachträglich alles mögliche als Zielformat (ps, pdf, html, etc.) erstellen.

Dann kam eine Zeitlang DocBook. Das war teilweise wirklich die Hölle. 
Ellenlange XML-Tags, die wiederum zu Editor-Makros führten, die ich dann nach 
drei Tagen wieder vergessen hatte. Dann gabs noch etliche Probleme die 
richtigen XSLT-templates herbeizubringen. Einarbeiten in XML, XSL etc. 
dringend notwendig. Allerdings bekommt man dann ein nahezu universelles 
Ausgangsformat (eben SGML-basiert), das recht gut in viele Zielformate 
transponiert werden kann. Aber letzten Endes, ist DocBook für die kurze, 
schnelle Doku. der Einstellungen von Treibern und Beschreibung von 
Installationsschritten zu überladen.

Und jetzt derzeit kommt alles in eine Wiki-Page rein. Da ist dann alles schön 
formatiert beisammen. Ich muß mir nur eine Handvoll Formatierungen merken. 
Für die Druckausgabe gibt's entsprechende Darstellungen. Eigentlich ideal. 
Wenn da nicht das Problem wäre, daß ich dazu einen Web-Server benötige. Und 
gleichfalls ist eine einfache Konvertierung in ein höherwertiges 
Ausgabemedium (Ausdruck, pdf, etc.) nicht möglich.

Alle beschriebenen Möglichkeiten bieten eine Klartext-Suche, so daß man auch 
ohne das jeweils produzierte Ausgabeformat an die Informationen kommen kann. 
Zudem sind alle gespeicherten Informationen platzsparend in ein 
Versionsverwaltungssystem aufzunehmen (ohne binary-diffs und andere 
Spielereien).


Wie macht Ihr eure Dokumentation? Ich suche quasi die eierlegende 
Wollmilchsau:

- schnelle Eingabe, wenig Tokens
- dennoch hervorragende Auszeichnungsmöglichkeiten, wie Aufzählungen,   
Formatierung, code-blocks, quotes, colours, sections, etc.
- textuelle Suche über alle Eintragungen auch ohne Zielformat möglich
- gewünschte Zielformate ohne Umwege: ps, pdf, html, txt
- Eingabe möglichst mit eigenem Text-Editor on-the-fly möglich 

Spricht viel für LaTeX, wenn da nicht die Komplexität wäre. Aber ein gutes 
Druckbild hat's ja. 

Ansonsten - irgendwelche Vorschläge? Oder Ideen?

Ciao, Georg

-- 
Georg Lohrer
GnuPGP-Key available on WebSite http://www.croxx.de

Attachment: pgp8B0pS6uHW5.pgp
Description: PGP signature


Reply to: