Software-Dokumentation im Team erstellen mit Wikis

Das gemeinsame Erstellen von Anforderungsdokumenten kennt man ja als Softwareentwickler: Der Product Owner schreibt, der Entwickler ändert oder kommentiert. Nach ein paar Schleifen steht dann ein fertiges Dokument. Wenn man aber technische Dokumentation erstellt, sind noch eine Menge mehr Leute involviert: Technische Redakteure, Entwickler, Marketing, Support und Endanwender. Das gibt oftmals ein ganz schönes Chaos, oder wird in einigen Unternehmen so strikt gehandhabt, dass die Dokumentation oft starr und veraltet wirkt.

Die Vorteile eines Wikis nutzen

Wir bei Atlassian benutzen das Enterprise Wiki Confluence zur Dokumentation unserer Software (-> Dogfooding: auch für Confluence). Wir haben 2 Seiten, die wir pflegen: Atlassian Anwender Doku und Atlassian Developer Doku. Bei uns erstellen neben den technischen Redakteuren auch Entwickler und Support die Dokumentation (und machmal auch unser CEO). Da wir nur 7 Redakteure haben, ist dies auch notwendig. Dazu kommen noch ca. 50 Helfer aus unserer Community.
Der Vorteil des Einsatzes eines Wikis sehen wir auch darin, dass Dokumentation und Zusammenarbeit unabhängig von geografischen Hürden und Zeitzonen erstellt werden kann. Ein Wiki steht immer und überall zur Verfügung.

Verantwortung übernehmen

Rechte: Es macht Sinn, an einigen Stellen die Rechte zu beschränken. In Confluence kann man Gruppen wie Entwickler, Redakteure und Community einrichten und die Rechte in verschiedenen Bereichen unterschiedlich vergeben.
Informiert sein: Man sollte immer über Änderungen informiert sein. Meist bieten Wikis einen Machanismus an, damit man über Email oder RSS-Feed immer auf dem Laufenden bleibt. Sie können dann regieren, wenn sie Zeit haben
Menschen beteiligen: Teilen Sie Inhalte anderen Personen mit und lassen sie diese an der Erstellung der Dokumentation teilhaben.
Verschicken Sie einen Link per Email oder benutzen sie die “Teilen”.-Funktion von Confluence. Die angesprochene Person kann sich dann einfach im Wiki einloggen und Inhalte verändern oder kommentieren.
Auch mal löschen: Hat jemand am Thema vorbeigeschrieben, oder ist eine Seite veraltet, sollte man nicht davor zurückschrecken auch mal Inhalte zu verschieben oder zu löschen. So bleibt ihre Dokumentation immer frisch (ist ja auch bei Quellcode so).

Kommentare nutzen

Die Kommentarfunktion ist eine der besten Features moderner Wikis. Man kann direkt in den Dialog mit dem Autor oder anderen an der Doku beitligten Personen einsteigen.

Achtung: Es können recht viele Kommantare werden, stellen Sie deshalb sicher, dass man die nötige Zeit und Resourcen hat, um sich auch darum zu kümmern. Nichts ist schlimmer, als die Kommentarfunktion anzubieten, dann aber nicht auf Anfragen zu antworten!
Nicht nur Dokumentation: Es werden meist nicht nur Kommentare zur Dokumentation gestellt. Meist sind es Fragen technischer Natur. Die technischen Redaktuere sollten sich also hier durch die Entwicklung unterstützen lassen.
Gegenseitige Hilfe: Das Beste, was passieren kann, ist, wenn eine Community entsteht, die sich gegenseitig hilft. Es gibt immer Fan-Boys der Produkte, die gerne anderen helfen möchten. Dadurch braucht auch die technische Redaktion weniger Resourcen. Unterstützen und bekräftigen sie ihre größten Fans.
Kommentar nicht erwünscht? Auf einigen Seiten machen Kommentare keinen Sinn oder sind nicht erwünscht. Schalten Sie die Kommentarfunktion für solche Bereiche ab.
Nett bleiben: Beiben Sie bei Antworten immer nett und höflich. Antworten Sie direkt und bestimmt, so wird ihre Wiki-gestützte Dokumentation zu einer guten Kommunikationsplattform.
Kommentare löschen: Ist eine Frage beantwortet, kann sie auch wieder nach einiger Zeit gelöscht werden. Passen Sie also ihre Doku an, wenn es hier ein Missverständnis gab, oder einige Dinge beschreiben wurden. Zu viele Kommentare lenken von der Dokumentation ab und helfen dem Benutzer nicht weiter, da diese meist nicht strukturiert sind. Wir löschen geklärte Kommentare bei Atlassian in der Regel nach 14 Tagen.

Die Verbindung halten

Wikis verbinden Menschen und verschiedene Aufgaben im Unternehmen miteinander. Gemeinsam kann man eine außergewöhnliche und frische Dokumentation erstellen. Ihre Nutzer werden es klasse finden, wenn Sie direkt mit Ihnen über Inhalte diskutieren können. Aber auch für Kollaboration im Unternehmen sind Dokumentationen in Wikis erstklassig geeignet.

Mehr über technische Dokuemtation mit Confluence gibt es auf unserer Webpage oder in Sarah Maddox Buch “Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication”

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: