Die Redakteuse

Das DITA-Open Toolkit unterscheidet im XHTML-Output zwischen Links auf Concepts, References und Tasks. Konkret werden die Links wie hier angezeigt:

Mal abgesehen davon, dass die vom Open Toolkit mitgelieferten deutschen Standard-Überschriften „Zugehörige Konzepte/Tasks“ etwas wunderlich klingen, bin ich persönlich kein Freund dieser Aufteilung der Links.

Ich habe z.B. an der Hochschule gelernt, dass solche Topic-Beziehungen klassifiziert und standardisiert werden sollten. Zum Beispiel indem man festlegt, welche Topictypen einander verlinken dürfen und wie. Das finde ich auch absolut okay und notwendig, denn so kann man verhindern, dass unsinnige Link-Urwälder entstehen in denen jedes Topic jedes andere Topic verlinkt, was dann am Ende nicht mehr sehr hilfreich für den Nutzer ist.

Aber: ich bin mir nicht sicher, ob diese Klassifizierung dem Nutzer an dieser Stelle unbedingt so vermittelt werden muss. Hat der Nutzer tatsächlich etwas davon, wenn ich ihm sage: hier kannst du verwandte Anleitungen finden und hier verwandte Erklärungen? Manchmal weiß der Nutzer doch selbst gar nicht so genau was er sucht und ist so eine Klassifizierung nicht vielleicht einfach nur ein Stolperstein?

In meinen Augen ringt so eine Aufteilung dem Nutzer noch einmal eine Entscheidung zuviel ab, die er auf der Suche nach der passenden Information treffen muss.  Er muss sich dann nochmal fragen: „Ja, was such ich denn eigentlich?“ und ehrlich gesagt ist man nicht in der Stimmung über so etwas nachzudenken, wenn man Hilfe sucht. Daher plädiere ich dafür verwandte Links unter einer Überschrift zusammenzufassen. Mir geht diese Aufteilung auf Nutzerseite einen Schritt zu weit und sie hat so ein bisschen was von „Ich mach es so. Weil ich es kann.“

Wie seht ihr das? Was macht ihr mit Links auf verwandte Themen und warum?

In meinem ersten Job wurde ich zur Betreuung der internen Dokumentation und des Firmen-Wikis eingestellt. Die Vision damals war, dass ich mal tüchtig aufräume und danach alle Abteilungen in der Firma tolle Dokumentation haben. Nun, das wäre super gewesen 🙂 Aber ich musste feststellen, dass das so einfach nicht ist. Es kommt zum einen darauf an, um was es sich für eine Abteilung handelt ( PR? Marketing?Personal? Entwicklung? Wenn ja, welche Richtung? etc), denn die Anforderungen sind dann natürlich unterschiedlich. Dazu hätte ich mich im Detail mit jeder Abteilung und ihrer Dokumentation auseinander setzen müssen. Eine Person alleine kann das für eine große Firma nicht schaffen – und: die Abteilungen müssen am Ende trotzdem auch immer noch selbst Dokumentation schreiben. Das war für die meisten die größte Überraschung damals 😉

In dem Vortrag „Documentation for Software Engineers“ von Ulrike Parson habe ich nun einiges erfahren, wie man das Thema interne Dokumentation angehen kann. Und es hat meine oben erwähnten Erfahrungen bestätigt.

Zielgruppen
Auch bei interner Dokumentation ist es wichtig sich über die Zielgruppe Gedanken zu machen. Das wird bei diesem Thema oft vergessen – es ist ja „nur“ für intern. Die Zielgruppe ist hier der Software-Entwickler und seine verschiedenenen Ausprägungen. Frei übersetzt teilte Ulrike Parson sie wie folgt auf:

• Den Praktiker:
  • will loslegen
  • benötigt Code-Kommentare, Code-Beispiele
• Den Gründlichen:
  • liest zuerst einmal die Grundlagen
  • benötigt Hintergrundinfo zu API/Framework, Beschreibung allgemeiner Programmieraufgaben (Error handling, Lokalisierung &Co.)
• Bedarfsleser
  • Liest bei konkreten Fragen nach
  • Benötigt Code-Kommentare, Hintergrundinformationen und Code-Beispiele

Anhand dieser Zielgruppenanalyse schlüsselt sie dann auf, welche Dokumenttyen geliefert werden müssen, um diesen Anforderungen gerecht zu werden. Und auch wie sie geliefert werden müssen, z.B. als PDF oder Wiki mit Feedback-Funktion, Index etc.

Die Rolle des technischen Redakteurs
Ich habe von Entwicklern schon so oft gehört, dass sie endlich mal dokumentieren müssten oder endlich mal „gescheit dokumentieren“ müssten. Gleichzeitig hab ich mich immer gefragt: wie könnte ich dabei helfen? Immerhin heißt es doch auch „technische Dokumentation“, was ich studiert habe 😉

Inwieweit der technische Redakteur die Entwickler beim tatsächlichen Dokumentieren unterstützen kann, hängt natürlich stark davon ab, wieviel Programmierwissen und -erfahrung er selbst hat. Aber es ist ununmgänglich, dass die Entwickler auch selbst dokumentieren – wer etwas selbst macht, weiß einfach am besten darüber Bescheid. Frau Parson hat sehr schön gezeigt, dass der Redakteur auch ohne selbst viel zu schreiben, doch sehr viel hier mitarbeiten kann.

So können die Aufgaben des Redakteurs aussehen:

• Zielgruppen- und Bedarfsanalyse
• Dokumentationsworkflows erstellen
• Terminologie erarbeiten, pflegen und bereitstellen
  • gerade in der Entwicklung lebt so manch uralter produktname ewig weiter
  • Missverständnisse untereinander werden vermieden
• Neue Texte redigieren/korrigieren
• Neue Texte evtl. schreiben
• Strukur der Dokumentation entwickeln und überwachen
• Dokumentvorlagen bereitstellen

Und wenn man sich das mal genau anschaut, sieht man wieder, dass das ganz klassische Redakteursaufgaben sind. Nur ist der Fokus nicht so sehr darauf alles auch selbst zu schreiben, sondern viel mehr zu recherchieren, strukturieren, den Entwicklern eine Basis zu geben.

Als praktisches Beispiel wurde abschließend noch ein Wiki gezeigt, das vor allem von den Entwicklern befüllt wird. Von der Redakteursseite wurde eine Grundstruktur angelegt und auch verschiedene Templates, damit die Entwickler nicht vor einer weißen Seite stehen und nicht wissen wo sie anfangen sollen. Der Redakteur überwachte nun die Entwicklung der Dokumentation und greift hier und da korrigierend ein. Zudem gibt es einen Freigabeprozess, so dass man auch wirklich nur qualitativ hochwertige Dokumentation publiziert.

Für den einen oder anderen Software-Entwickler klingt das ganze vielleicht nach zu viel Reglement, aber ich habe schon zuviel schlechte und veraltete SW-Dokumentation gesehen und das klingt für mich nach einem plausiblen Weg aus der Misere.

Fazit

Ein hochinteressanter Vortrag (als PDF), der auch mal neue Wege für Redakteure aufgezeigt hat, die nicht in der klassischen Schiene liegen, aber am Ende doch perfekt auf das Skillset passen. Vielen Dank dafür! 🙂

Desöfteren ist mir aufgefallen, dass hier und da die Terme „DITA“ und „DITA Open Toolkit“ miteinander vermischt werden – das mag ich als strenge Redakteuse nicht leiden. Beispiel: „DITA generiert das so und so.“ Jetzt muss ich einfach mal damit aufräumen und sagen:

DITA
Hier handelt es sich um die Darwin Information Typing Architecture. Das ist im Großen und Ganzen eine Ansammlung von DTDs und dahinter stehenden Konzepten, wie z.B. der Topic-Orientierung und der Vererbung/Spezialisierung. Hier wird also definiert, wie ich Topics schreibe und welche Elemente verwende. DITA an und für sich ist also mehr als eine Art Konzept und Regelwerk zu sehen.

DITA Open Toolkit
Wohingegen es sich beim DITA Open Toolkit um einen Baukasten mit verschiedenen Tools handelt, der etwas aus dem zaubert, das ich anhand des obigen Regelwerks produziert habe. Es ist eine schöne Ansammlung von Skripten und Stylesheets, deren Zusammenspiel am Ende aus den in DITA-XML geschriebenen Topics einen bestimmten Output (xhtml, pdf…) erzeugt. Das Toolkit ist also zur Transformation da, was eben auch heißt, dass man ohne das Toolkit trotzdem immer noch DITA „machen“ kann. Man könnte das gesamte Transformationsgerödel prinzipiell auch selber schreiben. Das Toolkit wurde im Endeffekt dafür entwickelt, um die Leute nicht vor eine große Hürde zu stellen, wenn sie DITA benutzen möchten, sondern ihnen schon direkt eine Transformationsbasis mitzugeben.

That’s all folks

So, es ist geschafft 🙂

Ich habe den Beinahe-Laptopausfall und die Vor-Vortrags-Nervosität halbwegs überstanden und ich denke, mein Vortrag ist ganz gut angekommen. Aber Genaueres weiß ich erst, wenn die Feedback-Bögen eintreffen. Und da bin ich äußerst gespannt! Meine Folien werde ich demnächst hier veröffentlichen sind nun unter Downloads erhältlich.

Nun, wie sah es mit dem Rest der Tagung aus?

Das Zielgruppen-Problem

Bei mir und bei vielen anderen (u.a. auch im neuentdeckten Blog von Jason A. Nichols), herrschte ein wenig Unmut darüber, dass man in vielen Fortgeschrittenen- oder Experten-Vorträgen dann doch wieder mit sehr vielen Basics konfrontiert wurde. Ich weiß schon gar nicht mehr in welchem Vortrag das war, aber als man anfing uns zu erklären, dass Standards gut sind, da kam ich mir etwas veräppelt vor (das gehört für mich zur Grundausstattung des Redakteurs!). Vielen fiel es sichtlich schwer, den Vortrag zielgruppengerecht aufzubereiten. Vielleicht fehlt aber auch ein genaue Beschreibung der Klassifikationen „Einsteiger – Fortgeschrittene -Experten“? Ich habe mir rückblickend nämlich überlegt, dass ich meinen Vortrag wohl besser als „Für Experten“ eingestuft hätte, aber so richtig sicher bin ich mir nicht. Daher mein Vorschlag an die tekom, da vielleicht mal den Versuch einer detaillierten Klassifikation zu starten. Als Zuhörer ist es wirklich sehr ärgerlich, wenn man sich in einem Vortrag wiederfindet, der einfach gar nicht passt. Ich kann mir gut vorstellen, dass sich viele die Investition in die nächste Tagung nochmal gut überlegen.

Die Idee von Urs Klenke nicht mehr so viele verschiedene Vorträge anzubieten, aber dafür ausgewähltere und diese auch zu wiederholen, finde ich prinzipiell auch ganz gut, wobei es organistorisch bestimmt ziemlich kompliziert wäre…

iPad, iPhone, ePub

Das war definitiv der Hype in diesem Jahr. Vieles war hier noch recht theoretisch – ich hoffe im nächsten Jahr auf erste richtige echte Beispiele!

User assistance

Der Hype dauert immer noch an, wobei ich da weiterhin hoffe, dass es auch hier noch mehr echte Beispiele geben wird. Die Theorie ist so langsam bekannt – jetzt will ich sehen was andere machen 🙂

… und der Rest

Es war einfach mal wieder nett so komplett unter „seinesgleichen“ zu sein und sich über das Fach austauschen zu können – und auch so einige Leute mal „in echt“ zu treffen 😉 Zielgruppen hin oder her – es waren immer noch Vorträge dabei, die einem hier und da wieder einen neuen Denkanstoß gegeben haben. Ich werde mir zum Beispiel in nächster Zeit einige Gedanken dazu machen, wie ich eventuell eine Verknüpfung meiner Hilfedateien mit den Textdateien unserer Applikationen hinbekommen kann, so wie in dem Vortrag „User Interface-Texte in der Dokumentation„.

Und last but not least: endlich ist mir bei einem von Tony Selfs Vorträgen eine Frage eingefallen! Dafür wird man nämlich mit einem echten Aussie-Koala belohnt 😉

EDIT: einen interessanten Rückblick bietet auch Sarah.

Die alljährliche tekom-Jahrestagung rückt näher und ich freu mich schon riesig.

Noch mehr freue ich mich, wenn ich den einen oder anderen Leser für meinen Vortrag „User assistance mit DITA“ gewinnen kann – gerne auch die Kollegen mitbringen 😉

Hier nochmal als Erinnerung, wann und wo ihr mich dort finden könnt:

User assistance mit DITA – Do 04.11., 11:15 Uhr, Raum 6.2