Handbuch schreiben

Kann man seine Software so gestalten, daß man ohne Handbuch auskommt? Selten oder nie. Anwender lieben gedruckte Unterlagen. Verkauft man ein Programm in hoher Auflage lohnt sich das Drucken. In der Projektarbeit sind gedruckte Handbücher zu teuer und nicht aktuell genug. Ich habe mehrere Versuche hinter mir, das Handbuch zum Teil der Datenbank zu machen. Im Prinzip bringt 4D alles Notwendige mit. Im Praktischen sind es die kleinen Annoyances, die es schwierig machen, ein 4D-Werkzeug einzurichten, das mir Arbeit abnimmt.

Es gibt sehr viele Werkzeuge, aber nur wenige sind wirklich geeignet, um klassische Handbücher zu erstellen. Klassisch heißt ausgedruckt und im Bett oder an anderen Orten lesbar. Mein Favorit ist, war, hat noch keinen Nachfolger, eigentlich, schade, noch immer nachtrauernd und, außerdem dies und das, also es ist

FrameMaker

Ab Version 5 kann FrameMaker fast alles, was ein modernes Handbuch ausmacht. Das fast habe ich eingefügt, weil die Stilformate leider nicht aufeinander aufbauen. Das ist schade, weil die Dokumenten-Hierarchie das gut fände, CSS es als Konzept mitbringt und RagTime das kann. Sonst ist in FrameMaker alles vorhanden, insbesondere:

  • Text auf dem Seitenrand
  • Bilder im Text mitfließend, vom Text umflossen und Bilder im Text verankert aber nach Regeln auf der Seite platziert
  • konditionellen Text, also mehrere Varianten in einem Dokument
  • Variablen im Fließtext, in Kopf- und Fußzeilen
  • leistungsfähige Inhaltsverzeichnisse und Indizes
  • sehr gute PDF-Erstellung incl. Inhaltsverzeichnisse und Indizes
  • macht bei komplexen Dokumenten nicht schlapp
  • ist schnell
  • die Version 7 kann PDFs einlesen bzw. referenzieren. Mein Grund von 5 auf 7 upzudaten.

Nein, InDesign ist leider kein Ersatz! FrameMaker 7.0 ist die letzte Version für Mac OS9 und funktioniert problemlos in Classic. Aktuelle Version ist 7.1 für Windows und Unix. Seit Adobe FrameMaker für den Mac eingestellt hat, gibt es eine FrameMaker für OSX-Petition. Dort findet sich eine umfangreiche Liste an Alternativen. Die Bewertungen dort sollten niemanden vom eigenen Ausprobieren abhalten. Es lohnt sich einen OS9-bootenden Mac oder Classic-fähigen PowerMac für FrameMaker am Laufen zu halten.

Genug Tränen für FrameMaker verdrückt. Eigentlich will ich kein Papier mehr herstellen. Ich hätte gerne was dynamischeres, weniger textlastig mit Bildern. Mehr ein Bilderbuch mit so viel Text wie eben nötig. Inzwischen habe ich mich auf eine Loseblatt-Sammlung eingeschoßen. Die Loseblatt-Sammlung kommt bei den Anwendern sehr gut an. Meine

Loseblatt Sammlungen

sind Anleitungen ohne feste Text-Struktur. Es sind graphische Darstellungen, Erläuterungen der Bildschirme und Ablauf-Skizzen. Die Loseblatt-Sammlung baut sich durch Fragen von den Anwendern auf und wird von mir als Anleitung für neue Funktionen verwendet. Beim Anwender landen sie als PDFs, meist im Querformat und in A3. Auf A4 ausgedruckt sind sie gut lesbar und die Bildschirmfotos sind scharf. Beispiele finden sich hier. Als Werkzeug verwende ich OmniGraffle. Dazu auch die4Dwerkstatt vom März '07.

Eigentlich will ich die Dokumentation und Handbücher in der Datenbank haben!

In der Datenbank

Ganz zu Anfang verwendete ich reinen Text und Bilder, hatte die Struktur in eigenen Feldern. Das ließ sich ordentlich darstellen. Bild und Text waren nicht so innig verzahnt, wie man es eigentlich erwartet. Das geht ganz gut, solange die Kapitel streng strukturierbar sind. Es klappte, habe sogar noch ein Bild gefunden.

Dann gab es 4D Write, eine richtige Textverarbeitung. In 4D Write sehen die Kapitel schöner aus. Rich Text und erkennbare Links sind angenehm. Leider behandelt 4D Write Bilder wie einen Buchstaben und das reißt den Text auf. Man könnte damit leben. Solange der Text in der Datenbank bleibt oder das Ausgabeziel Drucker oder PDF ist klappt es gut genug. Über Stilformate und HTML-Erzeugung in 4D Write will ich kommentarlos …

HTML und CSS

Diese WebSite pflege ich in HTML und CSS. Werkzeuge waren lange BBEdit, CSSEdit und Transmit. Diese Seite schreibe ich mit dem frischen Werkzeug Coda. Auch damit muß ich die HTML-Syntax beherrschen, die CSS-Syntax wird mir weitgehend abgenommen. Ich denke, das ist der Weg den ich in Zunkunft benutzen möchte: alle Handbuch-Inhalte sind in der Datenbank. Die Datenbank kennt die Struktur und übersetzt sie in HTML und verwendet die Darstellungsvorschriften aus dem CSS. Nur habe ich keinen Anreiz, HTML-Syntax im 4D-Textfeld ohne den von HTML-Editoren gewohnten Komfort einzugeben. Also weiche ich auf externe Werkzeuge aus.

4D LiveWindow

Mein Ideal: die Handbuch-Seite besteht aus Datensätzen. Text, Bilder und Links sowie CSS-Einstellungen sind verknüpft. Alle Seiten und Links werden frisch in der Datenbank erzeugt und innerhalb der Datenbank in einem 4D LiveWindow-Objekt dargestellt. Alles paletti, bis auf die Links. Um die benutzen zu können, muß der 4D-WebServer installiert sein und laufen. Könnte man nicht die Links in der dargestellten Seite sind mit dem Protokoll "4D://" referenzieren und so ohne installierten 4D-WebServer auskommen?

Darum bleibt fürs erste bei den Loseblatt-Samlungen!