Eddie VanArsdall veröffentlicht in seinem InfoDesign-Blog ausführliche Tutorials zu Madcap Flare. Das aktuelle Thema ist Flare Print Publishing: Creating Print–Only Topics.
Gerade beim Printoutput von Flare 3 nach Flare 4 hat sich einiges geändert (Stichwort: Page Layout statt Masterpage, hier gibts den Bericht eines anderen technical writer zu dem Thema). Es lohnt sich daher, auch bei Erfahrung mit Flare noch mal die Print-Formatierungen im Detail anzuschauen.
Tendenziell habe ich in der Vergangenheit wenig mit diesem oft kritisierten Tool gearbeitet, doch für ein Projekt bot sich das Erstellen der Unterlagen in Powerpoint an. Es ging darum, Schulungsunterlagen für Trainer und Teilnehmer aus derselben Quelle zu gestalten. Basis dafür war die Möglichkeit, die Folien und Notizen aus Powerpoint nach Word auszugeben (siehe auch Unterlagen im Dualen System).
Die Unterlagen
Die eigentliche Schulungsunterlage war in klassischem Folienformat (von meiner Grafikerin optisch ansprechend aufbereitet) und enthielt das Nötigste – was immer noch recht viel Information war. Hier ein Auszug:
Alle zusätzlichen Informationen, die nicht auf die Folie passten, wurden als Notizen ergänzt. Mit Ausgabe nach Word / PDF konnten die Teilnehmer so eine Unterlage mit Zusatzbemerkungen und Tipps erhalten.
Wo lagen die Herausforderungen?
Technisch ist das genaue Ausrichten von Folieninhalten und Notizen in Powerpoint ein wenig gewöhnungsbedürftig. Für die gelungene Ausgabe nach Word muss der Notizenmaster analog zu den Folien ans Corporate Design angepasst werden. Dennoch traten manchmal Nebeneffekte auf, da z.B. die Textausrichtung der Notizen in Word nicht immer sauber funktionierte.
Inhaltlich musste der Einstieg in eine komplexe Webanwendung so erklärt werden, dass die Teilnehmer nach der Schulung selbstständig Formulare erstellen können sollten. Dabei sollten die Inhalte mit viel Grafik schmackhaft gemacht werden. Dies führte zu starkem Kürzen oder Verteilen eines Vorgangs auf mehrere Folien. Die im Feinkonzept veranschlagte Folienanzahl wurde um 10% überschritten.
Resonanz der Teilnehmer
Die Unterlagen wurden gut angenommen, aber einige Folien enthielten immer noch zuviel Inhalte auf zuwenig Raum. Auch über thematische Erweiterungen wird noch nachgedacht. Vielleicht mehr dazu nächstes Jahr.
Fazit
Nicht unbedingt das stabilste aller Arbeitsmittel, bietet Powerpoint im Zusammenspiel mit Word doch einen Weg, um Inhalte für zwei Zielgruppen gleichzeitig zu verpacken. Da beide Programme zu den Bordmitteln der meisten Firmen gehören, ein praktischer Ansatz, wenn die Unterlagen nicht sehr oft angepasst werden müssen.
Manchmal google ich meinen Namen, wie dies alle Netzwerker tun, und war überrascht, einen Link auf ein Cubase 4 Tutorial zu finden.
Die Dokumentation zu Cubase 4 (in Deutsch und Englisch) war eins der wenigen Projekte, bei denen ich a) in einem echten Team gearbeitet habe und b) danach ein gebundenes Handbuch in Händen hielt. Meistens gibt es von meinen Tätigkeiten “nur” ein PDF oder HTML-Seiten als Ausgabe – in diesem Fall wurde das Produkt mit einer umfangreichen gedruckten Dokumentation ausgeliefert.
Die “traurige” Wahrheit ist allerdings, dass ich vom Thema Audiobearbeitung selbst nicht viel behalten habe. Und künstliche Instrumente für MIDI-Tracks sind zwar eine nette Sache, aber zum neuen Hobby hat es nicht gereicht…
Im Erklärblog gabs gerade eine nette Story zum Thema Bedienungsanleitung rettet Weihnachtsmann. Das ist doch mal eine Meldung wert :)
Hier einige Links und Erkenntnisse, die ich bei meiner aktuellen Arbeit mit Docbook zusammengesammelt habe.
Die Homebase: Docbook.org.
Tipps zu Docbook Markup.
Tipps zu Docbook XSL-FO.
Tipps zu Linking in Docbook.
The Complete Guide to Docbook XSL
Writing in Docbook, z.B. Useful Commands.
Docbook kann prinzipiell bedingten Text, dort “Profiling” genannt: Profiling in Docbook.
Gutes Einstiegsdokument in das Arbeiten mit Docbook: Docbook Primer von FreeBSD.
Robohelp X5 und 7 können Docbook importieren und exportieren. Das ist ggf. eine Möglichkeit, eine schönen Ouput nach Word/PDF zu erhalten.
Ein Ansatz für Standard Terminology inklusive Tags. leider unvollständig.
Und ein interessanter Artikel zum Thema Docbook – DITA: Lovely DITA, DocBook fades?. Von 2006, aber prinzipiell hat sich wenig geändert.
Als Editoren verwende ich aktuell ein Gespann aus Textpad (mit Docbook-Extension) für schnelleres Eingeben und XMLmind XML Editor zum Validieren und für bessere Übersicht beim Texte korrigieren.
Oldies but goldies… manuals of the past @ Wired:
Classic Computer Manuals and Plans from Apple and IBM
Classic Flight Manuals: B-58A, F-14A, Apollo, Gemini
A Photo Essay of Classic Instruction Manuals
And the real thing:
Documents from the NASA Technical Reports Server: Apollo and Apollo Soyuz Test Project
Im Cool-Stuff-Blog erschien neulich der Artikel Docs Aren’t Code. In diesem führt Eric Armstrong aus, warum es seiner Meinung nach wenig Sinn macht, Dokumentenfehler in einem traditionellen IT-Bugtracking-System wie Bugzilla oder TestTrack zu führen.
This post compares documentation and code, showing why bug reports and enhancement requests are so vital to the code base, and at the same time why those reasons simply do not apply to documentation.
Seine Argumentation beruht primär darauf, dass Fehler in der Dokumentation nicht dieselben profunden Auswirkungen wie Fehler in Code haben, und daher der entstehende Overhead eines Bugtrackings unnötig ist.
Hier stimme ich ihm durchaus zu. Was ich allerdings anders sehe, ist beispielsweise:
Doc bugs rarely track important information. Documentation is transparent. When something is wrong, there is little if any doubt as to what the problem is. There are no tests to devise, and no options to discuss. There are rare exceptions, in which case a bug report can play a useful role, but, typically, a writer talks to a content expert, gets the necessary information, and writes up the changes.
Jenseits von simplen Tippfehlern können Dokumentationsfehler durchaus Auswirkungen auf andere Bereiche haben. Beispielsweise können sie auf unschönes Verhalten der Bedienung und Oberfläche hinweisen (usability bug). Sie können auch auf eine Inkonsistenz zwischen Spezifikation und Entwicklung hindeuten oder auf eine fehlerhafte zugrundeliegende Annahme über das System von Seiten des Benutzers (=technischen Redakteurs), die an anderer Stelle im Dokument ausführlicher geklärt werden muss.
Erst im Kommentar führt Eric nochmals genau aus, gegen welche Art von Bugtracking er ist:
I’m against forcing them to be created and then closed for every single change a writer might want to make. [...] Since a single character change can cause an entire program to break, coders often get used to the mantra “a bug report for every change”. For code, that mantra proves its value time and again, with the result that coders may get wedded to the idea.
Er hat Recht, dass die aktuellen Richtlinien und Bugtracking-Systeme für Dokumente nicht geeignet sind. Daher arbeiten Redakteure vornehmlich mit handkorrigierten Papierausdrucken, Word-Dokumenten mit Änderungsverfolgung, langen Excellisten, PDFs mit Kommentaren und bei moderneren Systemen mit Überarbeitungsmarkierungen in den Topics.
Dennoch sehe ich nichts, was dagegen spricht, inhaltliche Fehler der Dokumentation in ein Bugtracking einzutragen, wenn mehrere Redakteure an denselben Inhalten arbeiten und sie kein anderes System haben, mit dem sie die Fehler leicht nachverfolgen können. Dass dabei nicht dieselben Maßstäbe wie bei Code-Bugs angelegt werden, ist ja nur eine Frage der Absprache.
Demnächst kommt wohl wirklich Madcap endlich mit einer DITA-Unterstützung. Was aber auf der Madcap-Seite angeboten wird, hilft mir bei meinem aktuellen Docbook-Problem leider nicht weiter.
Also doch erstmal XML-Editoren weitertesten…
Neulich stieß ich auf eine ältere Diskussion bei Coding Horror: How to Write Technical Documentation:
Welcome to the world of technical documentation! The situation you are in is no different from any other tech writer. The technical writing process:
1. Ask engineer how the damn thing works.
2. Deafing silence.
3. Crickets.
4. Tumbleweed.
5. Just start writing something. Anything.
6. Give this something to the engineer.
7. Watch engineer become quite upset at how badly you’ve missed the point of everything. [...]
Das Startposting ist eine amüsante Übertreibung (wobei mir der Ablauf nicht gänzlich unbekannt vorkommt). Aber wirklich interessant fand ich die Rückmeldungen von der Sorte:
Not sure why one would go to the developer? I prefer to play with the software myself, read/decipher business requirements and specs, and if all else fails, go to the business analyst, product manager, or whoever designed the thing and wrote the requirements/specs.
Ich rede zwar mit Entwicklern, es ist aber wirklich extrem hilfreich, sich vor dem Gespräch schonmal durch die verfügbaren Entwicklungsdokumente zu lesen. Für mich “tickt” jede Software auf eine bestimmte Weise, und dieses Ticken wird primär gebildet aus
a) der Vision, die am Anfang stand,
b) Design-Entscheidungen (Architektur und Prozesse),
c) in die Entwicklung eingeflossene Use Cases,
d) GUI-Design.
Das alles macht eine Software aus, und je besser man sie in ihrer Gesamtheit versteht, desto leichter kann man sie anderen verständlich machen. Und offensichtlich bin ich nicht die einzige, die diesen Total-Immersion-Ansatz fährt…sehr ermutigend. Der einzige Nachteil dabei: ich verstehe designbedingte Einschränkungen meist so gut, dass ich wenig Visionen für Verbesserungen habe.
Meine Tweets abonnieren 
Letzte Kommentare