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! 🙂