Da ich demnächst die Ehre habe, ein User Manual für ein in höchstem Maße umfangreiches Softwarepaket aus dem Finanzbereich zu erstellen, bin ich nun auf der Suche nach einem geeigneten Werkzeug hierfür.

Anforderungen:
- Ich editiere eine Quelle, setze da Querweise und daraus bekomme ich
* Fließtext mit Kapiteln (Zum Ausdrucken als Hardcopy)
* Hierarchische HTML-Dokumentation mit Links
[* Idealerweise noch ein nicht-proprietäres und daher parsebares Format; XML?]
- Auch die Sekretärin von nebenan soll das nutzen können (WYSIWYG).

Mein bester Ansatz bisher wäre LaTeX mit WYSIWYG-Editor (Lyx) und latex2html (das Hierarchie generiert). Allerdings reagieren meine Entwicklerkollegen eher allergisch darauf, weil latex2html angeblich eher unbrauchbaren Output produziert und LaTeX trotz intuitivem Editor zu komplex sei.

Weitere Ideen:
- docBook (zu krampfig mit der ganzen XSLT-Scheiße)
- Ein Wiki (DokuWiki) mit HTML-Dump-Plugin: Mühsam mit den Formatierungen und wie konvertiere ich das ohne großen Aufwand in Fließtext?
- div. unzureichende Software (AuthorIt wurde hier früher genutzt, ist aber angeblich zu mühsam und unbenutzbar; keine Ahnung, wie das in neueren Versionen aussieht.)

Anderer Ansatz (von wegen Bedienbarkeit) wäre http://www.doctohelp.com/
Das Ding kann lt. Homepage genau das, was ich brauche, wobei man Word direkt als Basis nutzen kann. Word ist halt leider Ranz und vor allem bei größeren Dokumenten (die Dokumentation wird umfangreich und stark bebildert) schwach.
Morgen werde ich das mal antesten; bis dahin bin ich für jeden Vorschlag dankbar.

Geld für Lizenzen spielt keine Rolle; Hauptsache ist, dass das Ding etwas taugt und obige Anforderungen erfüllt.

Vielen Dank schon mal.

„Und da wir uns ja seit heute etwas näher gekommen sind, kann ich nur sagen: Mir hilft da immer Norther volle Lautstärke (so wie jetzt), sodass die ganzen unrasierten, Wasserpfeife rauchenden, alternativen Wichsstudenten aus ihren, aus Bananenschalen und Abfall gebastelten, Sitzkissen fliegen.“

Wir verwenden an der Arbeit Doc-o-Matic. Das Ding ist zwar vor allem für Source- bzw. API-Dokumentation gemacht, allerdings ist es auch als normales Dokumentationswerkzeug relativ gut...
Export als .pdf und .html ist kein Problem (allerdings hab ich den .html-Export noch nie verwendet); ausserdem existiert afaik ein .xml-Export. Der Editor dazu ist einfach und bietet trotzdem eine gute funktionalität.
Ich würde das Ding auf jeden Fall in die Evaluation einbeziehen; eine 30-Tage-Testversion gibts auf der Webseite.

Doxygen

Zum Erstellen der API super, aber deine Ansprüche sprengen auch Doxy...

K:R-I)Z++
"CSS ist cascading style sheets. Und nicht so'n Ranzspiel." - dp
In memory of Voice († 2005/03/30)

Zitat:

hausi postete
Wir verwenden an der Arbeit Doc-o-Matic. Das Ding ist zwar vor allem für Source- bzw. API-Dokumentation gemacht, allerdings ist es auch als normales Dokumentationswerkzeug relativ gut...
Export als .pdf und .html ist kein Problem (allerdings hab ich den .html-Export noch nie verwendet); ausserdem existiert afaik ein .xml-Export. Der Editor dazu ist einfach und bietet trotzdem eine gute funktionalität.
Ich würde das Ding auf jeden Fall in die Evaluation einbeziehen; eine 30-Tage-Testversion gibts auf der Webseite.

Fragen, die noch offen sind:
- Der generierte HTML-Baum verfügt über keinerlei Suchfunktion (ebenso die Online-Hilfe der doc-O-Matic-Website). Gibt es die Möglichkeit (Plugin), so etwas zu generieren oder muss man wirklich Hand anlegen?

- Lohnt sich der Kauf einer Serverlizenz? Wie arbeitet der Server? Checkt der CVS und/oder Subversion aus und erstellt dann eine zugängliche Dokumentation?

Vielleicht kannst du, hausi, noch ein paar Worte darüber verlieren.

„Und da wir uns ja seit heute etwas näher gekommen sind, kann ich nur sagen: Mir hilft da immer Norther volle Lautstärke (so wie jetzt), sodass die ganzen unrasierten, Wasserpfeife rauchenden, alternativen Wichsstudenten aus ihren, aus Bananenschalen und Abfall gebastelten, Sitzkissen fliegen.“

Ich kann dir dabei leider auch nicht weiterhelfen. Wir verwenden nur den WinHelp- und den PDF-Export für die Release Notes. Eine Suchfunktion fällt da natürlich weg und die Server-Lizenz war für uns auch nie interessant. Ich kann dir aber allgemein empfehlen denen einfach eine Mail zu schicken. Wir haben immer innerhalb weniger Stunden eine gute Antwort bekommen und die können dir bei diesen Fragen auch sicher weiterhelfen.

Ich hole den Thread noch einmal aus der Versenkung, um vielleicht jemandem, der selbst einmal so etwas zu suchen hat, zu helfen.

Zunächst:
Die Wahl ist schlussendlich (siehe obige Anforderungen) doch auf doc-to-help (das meiner Ansicht nach eigentlich herrenlos überteuert ist) gefallen.
Preis: USD 749,95 (beinhaltet 1 Jahr Updates)
oder USD 999,99 (Team-Editing-Support und „Natural Search im Export“)

Im Prinzip ist das Ding nichts Anderes als ein Projektmanager für deine Dokumente, die du mit Word bearbeitest. Ich halte das für mittelmäßig sinnfrei, jedwede Dokumentation mit MS Word zu bauen (siehe ganz unten), aber „was muss, das muss“.

Fakten:
- Ausgabeformate sind: HTML-Baum mit Suche, PDF, CHM.
- Es gibt verschiedenste Einstellmöglichkeiten für die Aufbereitung der Ausgabe, was v. a. für HTML sehr nützlich ist. Nicht immer sehr intuitiv, aber erfüllt alle Anforderungen.
- Integriert sich via Plugin direkt in Word mit eigenen Formatierungsmöglichkeiten, die das Parsen vom Dokument für die Konvertierung dann vereinfachen (dth speichert die Word-Files direkt als HTML-Seiten und parst diese dann.).
- HTML-Output ist nicht standardkonform und hat allerhand Javascript mit dabei.
- HTML-Output ist leicht anpassbar.

http://www.doctohelp.com/

Warum doch doc-to-help? Der WYSIWYG-Editor von doc-O-Matic wirkte schlussendlich doch zu umständlich und unausgereift. Grenzen werden schnell aufgezeigt, wenn man das Ding primär fürs Authoring benutzen wollte.

Aus Entwicklersicht: doc-O-Matic fehlt Unterstützung für wichtige Programmiersprachen (einige werden mit der nächsten Version nachgesteuert) und der Generic-Support ist einfach nur zu schlecht.

Darum wird für das automatische Generieren von Code-Dokumentationen hier in Zukunft doxygen draufgeklatscht, das halt in regelmäßigen Abständen dazu angehalten wird, automatisch Dokumentation zu bauen. (doxygen ist kostenlos und Open Source)

Zur Auswahl standen außerdem:
doc-O-Matic:
Kosten: USD 999,00 pro Desktop (nur Authoring-Version: USD 299,00)
Serverlizenz: USD 3.499,00

- Viele Enterprisefeatures (die wir entweder nicht brauchen oder doxygen für uns schon hat.)
- Serverlizenz herrenlos teuer.
- Integrierter Editor
- Output auch XML neben PDF, HTML, CHM

http://www.doc-o-matic.de/

Word-2-Web
Kosten: USD 249,95 pro Desktop.
- Konverter von Word nach HTML
- Sehr simple Ausgabe
- Sehr beschränkter Funktionsumfang und kaum Anpassungsmöglichkeiten.
http://www.macrobject.com/en/word-2-web/purchase.htm

AuthorIT
Ein einziger Krampf. Ich dachte, ich müsse Krebs von der Bedienung bekommen.

LaTeX + latex2html
- Kein WYSIWYG (LaTeX halt...), wobei man mit LyX als Editor das quasi auch am Start hat, ohne den Sinn von LaTeX ganz ad absurdum zu führen.
- Konnte ich nicht testen, aber vielversprechend.
- Plattformunabhängig

Einige andere sind nicht der Erwähnung wert, wenngleich sie auch „getestet“ wurden.

Generell für Dokumentation:
----------------------------
Top (aber HTML-Baum „is nicht“):
XMLMind + docbook + Converter
XMLMind ist ein XML-Editor, der zB für das docbook-Format (XML) eine WYSIWYG-Präsentation bereitstellt. Mit geeignetem Konvertierungswerkzeugen für zB PDF (von der Homepage von XMLMind beziehbar) eine sehr günstige und zugleich mächtige Variante (da immer auch XML direkt bearbeitet werden kann).
- Plattformunabhängig
- äußerst preisgünstig (für den Privatgebrauch ohne Konvertierungsmöglichkeiten sogar kostenlos)
- sehe ich persönlich für den Firmeneinsatz als überlegen an, um $Dokumentation zu bauen, wobei ich hier natürlich aus Ermangelung an Zeit nicht die Enterpriseprobe machen konnte.

http://www.xmlmind.com/xmleditor/
http://www.docbook.org/

„Und da wir uns ja seit heute etwas näher gekommen sind, kann ich nur sagen: Mir hilft da immer Norther volle Lautstärke (so wie jetzt), sodass die ganzen unrasierten, Wasserpfeife rauchenden, alternativen Wichsstudenten aus ihren, aus Bananenschalen und Abfall gebastelten, Sitzkissen fliegen.“