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:
pgpe_pr_5s0M9.pgp
Description: PGP signature