Was verwendet Ihr für Handbücher?

Scorcher24

Wie schreibt Ihr eure Handbücher und Readme-Daten etc?
Verwendet Ihr DocBooc, BoostBook oder ähnliche?

Ich persönlich verwende momentan die docutils von Sourceforge und davon den Restructured Text (rst), aber so ganz gefällt mir das nicht, v.a. weil der keine code-tags kennt :).
Freu mich auf Antworten :).
rya.

ps.: Über nützliche Links zum Thema DocBooc-Tutorials oder Vereinfachungen des ganzen würde ich mich auch freuen.

Geht es um technische Dokumentation?
Ich nutze für C++ Doxygen, als Editor Notepad++. Doxygen hat den Vorteil, das man wenig Syntax in seine Prosa schreiben muß. Bzw. man kann recht einfache Kommandos nutzen.

In unserem Java-Projekt benutzen wir DocBook, finde es aber schrecklich, weil alles XML ist. Und XML ist echt mies für den Menschen zu schreiben und lesen. Ein Tag falsch oder vergessen, und alles ist dahin. Vorallem weil wir kein gutes Tool dafür haben, weshalb ich Notepad++ dafür nutzen muß.

Wenn ich ein Benutzerhandbuch schreiben sollte, würde ich in Zukunft LaTeX nutzen. Habe mir dazu ein Buch gekauft und finde es beeindruckend, was man damit alles machen kann... vorallem wie gut das Ergebnis ist.

Ich verwende dazu Org-Mode und den LaTeX Export, ist aber sicher nicht jedermanns Sache.

EXDW

also ich lass eine xml datei beim bau generieren, und schick am ende einfach sandcastle drueber, der generiert mir ne htm hilfe datei als doku (alles c# only)

Scorcher24

Also es geht mir um out-of-source-doku, nicht um Source-Doku, da ist doxygen optimal :). Und mithilfe des XML-Interfaces lässt sich da ja alles generieren.

Es geht mir darum, dass ich für mein aktuelles Projekt Angelwing (aka Angeldust, aber da machten sich zuviele Leute drüber lustig wegen dem nicht gewollten Bezug zu Drogen :p) ein Handbuch schreiben möchte für den Endanwender und mir ist Doxygen dafür zu.. hm naja es ist für Sourcen toll, aber nicht für Handbücher :).

Latex hab ich noch nie verwendet, Docbook ist mir zu kompliziert, weil wie Bulli schrieb, XML-Dateien sind für sowas grausam für einen Menschen.
Docutils sind ganz nett, aber die Möglichkeiten zur Formatierung sind mir zu begrenzt und von Tabs bzw Einrückungen abhängig. Und sowas mag ich ja gar nicht :-). Btw als Editor verwende ich conTEXT unter Win32, der rockt schon derbe. Unter Linux KATE.
Bei Boost::Book hatte ich so den Eindruck, dass iwie die Hälfte der Doku fehlt, bzw die Abhängigkeit zu bjam is ja grauenhaft. Weil mit bjam konnte ich noch nie umgehen hehe. (Ein wenig Offtopic, aber habt ihr mal mit 0 plan von bjam das Tutorial von bjam ausprobiert? Ich krieg das nicht kompiliert, sorry aber ich bin für boost wohl zu blöde).

Wie schreibts sichs denn mit Latex so? Hast mal nen gutes englisches oder deutsches Tutorial? Gibts gute Tools mit denen das schneller von der Hand geht?
rya.

Scorcher24 schrieb:

[...] Gibts gute Tools mit denen das schneller von der Hand geht?
rya.

Solche Tools gibt es eines davon wäre Lyx, das ist ein Word-Processor der eben LaTeX generiert. Außerdem kannst du dort an jeder Stelle selbst Hand anlegen und TeX-Code einfügen.

Ansonsten halt wie gesagt Org-Mode, damit kann man sehr viel machen und ab dem Moment wo es nicht mehr ausreicht einfach nach LaTeX exportieren und von da an den LaTeX Code weiterbearbeiten.

Scorcher24

Lyx sieht gut aus, werde ich mir heute abend mal reinziehen. Danke dir :).
rya.

Scorcher24 schrieb:

Es geht mir darum, dass ich für mein aktuelles Projekt Angelwing (aka Angeldust, aber da machten sich zuviele Leute drüber lustig wegen dem nicht gewollten Bezug zu Drogen :p)

:p

hellihjb

Ich persönlich verwende momentan...

Ich verwende dafuer meine Sekretaerin - ein hervorragendes Tool :p

hellihjb schrieb:

Ich persönlich verwende momentan...

Ich verwende dafuer meine Sekretaerin - ein hervorragendes Tool :p

Pfui du Ferkel

Scorcher24 schrieb:

Also es geht mir um out-of-source-doku, nicht um Source-Doku, da ist doxygen optimal :).

Na, ich benutze es auch für die Nicht-Source-Doku! Wie gesagt, super einfach dafür geeignet.

Scorcher24 schrieb:

Es geht mir darum, dass ich für mein aktuelles Projekt Angelwing (aka Angeldust, aber da machten sich zuviele Leute drüber lustig wegen dem nicht gewollten Bezug zu Drogen :p)

Wenn du uns schon hier nen namen nennst, zeig uns auch gleich die Homepage dazu.

Scorcher24 schrieb:

Bei Boost::Book hatte ich so den Eindruck, dass iwie die Hälfte der Doku fehlt, bzw die Abhängigkeit zu bjam is ja grauenhaft. Weil mit bjam konnte ich noch nie umgehen hehe. (Ein wenig Offtopic, aber habt ihr mal mit 0 plan von bjam das Tutorial von bjam ausprobiert? Ich krieg das nicht kompiliert, sorry aber ich bin für boost wohl zu blöde).

bjam bzw. BBv2 ist eigentlich ziemlich cool. Wenn man natürlich daran scheitert bjam.exe zu erstellen, hat man ganz andere Probleme. Aber die Scripte für gängige Projekte sind einfach erstellt.
Die BBv2-Doku ist übrigens die letzten Jahre mächtig verbessert wurden. Ich kann da nur empfehlen mal wieder rein zu schauen. Ansonst gibts auch noch hier ein interessantes Tutorial für den Einstieg:
http://www.kharchi.eu/wiki/doku.php?id=cpp:boost:bbv2

Scorcher24 schrieb:

Wie schreibts sichs denn mit Latex so? Hast mal nen gutes englisches oder deutsches Tutorial?

Ich würde dir ein vernünftiges dt. Buch empfehlen. Es gibt unterschiedliche Bücher über LaTeX. Ich selber habe mir ein Buch über Typgraphie gekauft, welches LaTeX als Werkzeug nutzt. D.h. man lernt nicht primär wie man Latex nutzt, sondern wie man vernünftiges Layout, Schriftsatz usw. macht, MIT LaTeX:
http://www.addison-wesley.de/main/main.asp?page=ebooks/bookdetails&productid=167949
Danach weiß man erst, wie schlecht heute die selbstgemachten Dokumente, Schriftstücke und Bücher sind... Mit dem Buch und LaTeX bekommt man geniale Ergebnisse! Eine ganz banale Sache aus dem Buch: Unterstreichungen sind heute Tabu!!! Hätte ich nie gedacht! Denn Unterstreichung war nur zu Schreibmaschinenzeiten die einzige Möglichkeit (außer alles in Großbuchstaben) ein Wort hervorzugeben. Außer man macht einen auf Schreibmaschine, dann ist das heute erlaubt.
Man lernt sehr viel, um professionelle Dokumente erstellen zu können. LaTeX hilft da mit Vorgaben ungemein, aber wenn man weiß warum und wie, ist es ne gute Investition.
Da ist auch eine komplette Live-Distribution auf DVD drauf, für Linux und Windows.

Echtes Buch mit DVD:
http://www.addison-wesley.de/main/main.asp?page=deutsch/bookdetails&productid=132045
Das andere war nur das ebook.

Scorcher24

Wenn du uns schon hier nen namen nennst, zeig uns auch gleich die Homepage dazu.

Eigentlich wollte ich keine Werbung machen :). Aber da du drauf bestehst: http://angelwing.googlecode.com. Source oder Releases gibts im laufe dieser oder nächster Woche. Hab das Ding eigentlich in der ersten Beta fertig, aber ich trenne gerade Compiler vom Frontend. Und natürlich fehlt das Handbuch :p.

bjam bzw. BBv2 ist eigentlich ziemlich cool. Wenn man natürlich daran scheitert bjam.exe zu erstellen, hat man ganz andere Probleme. Aber die Scripte für gängige Projekte sind einfach erstellt.
Die BBv2-Doku ist übrigens die letzten Jahre mächtig verbessert wurden. Ich kann da nur empfehlen mal wieder rein zu schauen. Ansonst gibts auch noch hier ein interessantes Tutorial für den Einstieg:

Hey, wie man es bastelt weiss ich *g*.
Nur die Handhabung von BJam fällt mir nicht einfach. Aber das Tutorial schaut besser aus als das von boost selbst. Schau ich mir an :).

Danke für den Link für das Buch. Evtl kauf ich das bei Gelegenheit, ist notiert, hab momentan noch ein anderes zu lesen hehe. ( "StarBasic und OpenOffice-Makros" vom Dingsbein, lese ich aktuell, sowie "Millionär" von Tommy Jaud ).

rya.

Scorcher24 schrieb:

Wenn du uns schon hier nen namen nennst, zeig uns auch gleich die Homepage dazu.

Eigentlich wollte ich keine Werbung machen :). Aber da du drauf bestehst: http://angelwing.googlecode.com. Source oder Releases gibts im laufe dieser oder nächster Woche. Hab das Ding eigentlich in der ersten Beta fertig, aber ich trenne gerade Compiler vom Frontend. Und natürlich fehlt das Handbuch :p.

bjam bzw. BBv2 ist eigentlich ziemlich cool. Wenn man natürlich daran scheitert bjam.exe zu erstellen, hat man ganz andere Probleme. Aber die Scripte für gängige Projekte sind einfach erstellt.
Die BBv2-Doku ist übrigens die letzten Jahre mächtig verbessert wurden. Ich kann da nur empfehlen mal wieder rein zu schauen. Ansonst gibts auch noch hier ein interessantes Tutorial für den Einstieg:

Hey, wie man es bastelt weiss ich *g*.
Nur die Handhabung von BJam fällt mir nicht einfach. Aber das Tutorial schaut besser aus als das von boost selbst. Schau ich mir an :).

Danke für den Link für das Buch. Evtl kauf ich das bei Gelegenheit, ist notiert, hab momentan noch ein anderes zu lesen hehe. ( "StarBasic und OpenOffice-Makros" vom Dingsbein, lese ich aktuell, sowie "Millionär" von Tommy Jaud ).

rya.

pluginable

Wie wäre es mit "pluggable"?

frenki

Wir verwenden Help & Manual.

Bulli schrieb:

Denn Unterstreichung war nur zu Schreibmaschinenzeiten die einzige Möglichkeit (außer alles in Großbuchstaben) ein Wort hervorzugeben.

Von S p e r r d r u c k mal ab. Das war schon zu Urgroßvaters Jugendzeit möglich, falls Unterstreichung gerade ausverkauft war.

frenki schrieb:

Wir verwenden Help & Manual.

Hmm, das ist kommerziell :D. Aber danke.

Also ich hab mir Lyx gestern abend mal reingezogen und bin begeistert. So schnell und einfach hab ich noch nie Doku geschrieben :D. Und das ohne einen Funken Ahnung von LateX. Und schaut super aus.
rya.