Dokumentation / Howtos schreiben

[roman]

Hallo zusammen,

da ich in naechter Zeit ein paar Dokumentationen und Howtos schreiben muss wollte ich nachfragen wie ihr das handhabt. Folgende Anforderungen sind wichtig:

1. Das Resultat soll in HTML vorliegen
2. Mehrere Kapitel auf mehreren Seiten mit Index
3. Leicht wartbar, sprich am besten so ne Art Metasprache die dann uebersetzt wird

Zur besseren Anschauung hab ich unter [1] mal ein Beispiel aufgefuehrt.
Ich hab natuerlich schon google verwendet und bin dabei ueber docbook gestolpert, scheint genau das zu sein was ich suche, ist mir aber viel zu maechtig und ich hab keine Zeit und Lust mich da richtig durchzudenken. Deshalb meine Frage: Wer von euch kennt ein Programm mit dem ich oben genannte Sachen schnell und moeglichst unkompliziert erledigen kann?

Danke im Vorraus!


[1] http://tldp.org/HOWTO/LILO.html

 

[Yamagi]

Du hast die Wahl zwischen Docbook (es gibt noch einige wenige ähnliche Systeme afaik) und LaTeX. Beides ist in der Zielsetzung ähnlich und wird wohl beides deine Anforderungen erfüllen. Die Frage ist mehr: Was ist für dich einfacher zu lernen?
Docbook gilt im allgemeinen als intuitiver, gerade wenn man sich schon mit SGML-Artigen Sprachen beschäftigt hat. Latex hingegenn sagt man wenigstens, bietet wohl deutlich mehr Möglichkeiten.

Jetztentlich kann ich dir auch keinen klaren Rat geben. Es kommt stark auf deine Vorerfahrung und deinen Lernwillen an. Außerdem habe ich keine Ahnung, wie Latex überhaupt für deine Zwecke geeignet ist. Ich weiß nur, dass es möglich wäre. Es wird aber wohl seinen Grund haben, dass die meisten großen Doku-Projekte (FreeBSD Doku, TLDP, ...) auf Docbook setzen.

 

[steinlaus]

Zwar kenne ich es nicht persönlich, habe aber hier und da schon mitbekommen das AsciiDoc wohl "ganz nett" sein soll. Vielleicht eignet es sich ja für deine Anforderungen und du kannst damit etwas anfangen...

 

[soul_rebel]

vielleicht doofe frage, aber kann man sowas nicht einfach und unkompliziert mitm office-paket wie koffice oder ooo machen und dann nach html-exportieren?

 

[Kamikaze]

Ich würde Docbook vorschlagen, das setzt sich so langsam durch. Soweit ich weiß gibt es die Möglichkeit das nach HTML, Postscript oder PDF zu konvertieren.

http://www.freebsd.org/docproj/sgml.html

Ist ein guter Startpunkt.

 

[zippelmann]

wenn Du die htmls nicht mit Dir rumschleppen willst ist mediawiki auch ne nette sache.

 

[jtsn]

da ich in naechter Zeit ein paar Dokumentationen und Howtos schreiben muss

Welcher Art?

hab keine Zeit und Lust mich da richtig durchzudenken.

Wie verträgt sich das mit Dokumentation schreiben?

Wer von euch kennt ein Programm mit dem ich oben genannte Sachen schnell und moeglichst unkompliziert erledigen kann?

Das Programm heißt gvim, die Arbeit mußt Du allerdings schon selbst machen.

ciao, jtsn

 

[thyrver]

jtsn hat recht, deine Anforderungen sind unscharf formuliert. So bestehen alle Möglichkeiten, von html direkt in Notepad schreiben bis zum CMS mit der Möglichkeit das ganze im Browser zu machen. Dazwischen gibts LaTeX in Lyx (oder auch gvim...) mit Export in html, doxygen, docbook, MS-Word mit html-Export...

Unabhängig von der Dokusystem-Diskussion ist ein Artikel von Su-Shee in der Datenschleuder auch ganz interessant: http://ds.ccc.de/081/maulhelden

 

[roman]

Zuerst mal Dank für die Antworten

Du hast die Wahl zwischen Docbook (es gibt noch einige wenige ähnliche Systeme afaik) und LaTeX.

Manchmal sieht man den Wald vor lauter Bäumen nicht mehr, dank LaTeX2HTML kann man das sogar ansehlich konvertieren, dass passt echt wie die Faust aufs Auge

Zwar kenne ich es nicht persönlich, habe aber hier und da schon mitbekommen das AsciiDoc wohl "ganz nett" sein soll.

Vielen Dank steinlaus, ich habs mir angeguckt und gefaellt mir sehr gut.

Kamikaze]
Ich würde Docbook vorschlagen, das setzt sich so langsam durch. Soweit ich weiß gibt es die Möglichkeit das nach HTML, Postscript oder PDF zu konvertieren.

http://www.freebsd.org/docproj/sgml.html

Ist ein guter Startpunkt.

Danke fuer den Link, ich habe so das Gefühl das es sich doch lohnen würde in docbook Zeit zu investieren.

vielleicht doofe frage, aber kann man sowas nicht einfach und unkompliziert mitm office-paket wie koffice oder ooo machen und dann nach html-exportieren?

Die Frage ist ganz und gar nicht doof. Da kommen meine persönlichen Vorstellungen mit ins Spiel, die ich zugegebenermaßen oben nicht genannt habe. Alle Programme die mit einem k anfangen sind mir suspekt und um OOo zu kompilieren und zu starten lebe ich nicht mehr lange genug

wenn Du die htmls nicht mit Dir rumschleppen willst ist mediawiki auch ne nette sache.

Danke, kommt für mich aber nicht in Frage.

Welcher Art?

Berechtigte Frage.
1. physikalische Ausarbeitungen - lässt sich mit LaTeX2HTML prima erschlagen
2. Howtos der Art: 'Wie benutzt man silo / awk / gnuplot etc. - asciidoc scheint dort geeignet zu sein

Das Programm heißt gvim, die Arbeit mußt Du allerdings schon selbst machen.

Das Programm heißt definitiv _nicht_ gvim, ich suche nämlich keinen Editor und das ich mir selber die Arbeit machen muss ist mir auch klar. Völlig unnützer Kommentar den ich aber schon erwartet habe. Das nächste Mal schreibe ich das in meiner Anfrage oben mit rein *kopfschüttel*

Unabhängig von der Dokusystem-Diskussion ist ein Artikel von Su-Shee in der Datenschleuder auch ganz interessant: http://ds.ccc.de/081/maulhelden

Was soll mir das sagen? Das ich zu unvollständig war in meiner Frage?

 

[juedan]

Hallo roman,

in unserer Firma (UNIX-Bereich) verwenden wir für Schulungunterlagen, Dokumentationen und Serienbriefe nur TeX/LaTeX. Der Grund: perfektes Layout, leichte Wartbarkeit des Codes, leichtes Erzeugen eines Globaldokuments und die Druckerei, bei der wir drucken lassen, akzeptiert das DVI-Format. Selbst Howtos usw. werden in Tex/LaTeX erstellt.
Ausnahmen: OpenOffice für Präsentationen, Einzelbriefe und Tabellenkalkulation.

Vielleicht hilft es bei der Entscheidungsfindung

Viele Grüße

Jürgen

 

[thyrver]

Was soll mir das sagen? Das ich zu unvollständig war in meiner Frage?

Nein, überhaupt nicht. Wenn du schon dokumentiert hast, und weißt, wie du gute Dokumentation schreibst, dann hilft es dir nicht. Wenn du das noch nicht gemacht hast, oder das was du schreibst nicht in der Qualität ist, die du selbst erwartet hast, dann hilft dir der Link vielleicht. Und wenn nicht, dann hilft es vielleicht irgendjemand anderem, der dokumentieren muss, ein System hat, aber nicht die richtigen Worte findet.

Und wenn das alles nicht zutrifft, dann ist der Kommentar noch immer mindestens so wertvoll wie viele andere Offtopic-Kommentare (inclusive diesem Kommentar hier).