Blog

Eine Tasse auf Reisen #5 - die Auflösung

In welchem Land wurde die parson-Tasse fotografiert, haben wir Anfang Dezember gefragt. Die Frage war knifflig. Trotzdem kamen die meisten auf die richtige Antwort: Kuba. mehr ...

RDF is not XML – RDF serialization and iiRDS metadata

The world of technical writing loves XML. Its document type definitions are the foundation of structured authoring. XML and the underlying schemas structure the content of our information products. The benefits are twofold. Content is consistently structured and easy to read. Authors have an easier time writing the content. The structure provides guidelines for authoring. mehr ...

Gewinnspiel: Eine Tasse auf Reisen #5

Brrr…in Hamburg ist der Winter eingekehrt und Weihnachten steht vor der Tür. Die parson-Tasse lässt sich währenddessen die Sonne auf den roten Bauch scheinen. mehr ...

How to become a technical writer – Confessions of a former translator

A former translator, I worked the first seven years of my professional life in the translation industry, in various positions. While I learned a lot from this experience, it also left me, as a writer, frustrated. Translators are chained to their source text and writing the words of others in another language, usually focusing on what their clients want. mehr ...

tekom-Impressionen Teil 2: API-Dokumentation und die VUKA-Welt

Daniela Herbold und Ulrike Parson berichten über Leitlinien für eine optimierte API-Dokumentation sowie Lösungsansätze für eine innovative Personalführung. mehr ...

Dokumentation. Das notwendige Übel?

Mitternacht, irgendwo in Deutschland. Anna sitzt an ihrem Schreibisch. Sie hat den Kopf in die Hände gelegt und starrt vor sich auf den Bildschirm. Anna ist Software-Entwicklerin. Seit kurzem arbeitet sie bei einer Firma, die spezialisierte Erweiterungen für eine kaufmännische Standardsoftware verkauft. Für die Entwicklung dieser Erweiterungen soll Anna das API (Application Programming Interface) der kaufmännischen Software verwenden. Aber Anna hat ein Problem. Sie weiß nichts über das API – seine Struktur, die Schnittstellen, die angebotenen Funktionen. Das API ist sehr spärlich dokumentiert. Die fehlende Dokumentation kostet sie und ihren Arbeitgeber Zeit und Geld und droht mittlerweile das Projekt zum Scheitern zu bringen.

 checkmarkEine gute API-Dokumentation …

  • erklärt grundlegende Konzepte und Funktionen,
  • hebt wichtige Anwendungsfälle hervor,
  • beschreibt ausführlich die meistgenutzten Schnittstellen.

Gleiche Zeit, anderer Kontinent. Es klopft an Jims Tür. Jims Assistentin Sandy betritt den Raum. Jim ist Projektmanager der Firma, die die Software entwickelt, an dessen API Anna gerade verzweifelt.

Sandy sieht besorgt aus. “Ich habe schon wieder einen wütenden Anruf von einem unserer technischen Partner bekommen. Er sagt, sie werden aus dem Partnerprogramm aussteigen, weil die Dokumentation der API so schlecht ist, dass die Entwicklung von Erweiterungen einfach zu aufwändig für sie ist.”

Jim verdreht die Augen. So kann es nicht weitergehen. Das leidige Thema Dokumentation entwickelt sich zu einem wirtschaftlichen Problem. Er beschließt, mit dem verantwortlichen Software-Architekten zu reden. Auf dem Weg durch das Firmengebäude kommt Jim am Besprechungsraum vorbei. Durch das Sichtglas in der Tür sieht er, wie Ben, der Leiter des Softwareentwicklungs-Teams, ein Diagramm auf das Whiteboard zeichnet und etwas erklärt. Am Besprechungstisch sitzt ein junger Mann und hört aufmerksam zu.

Jim steckt den Kopf durch die Tür und begrüßt die beiden. Ben stellt den jungen Mann vor: "Das ist Michael, unser neuer Praktikant.”

“Willkommen im Team”, sagt Jim. Er dreht sich zum Whiteboard. “Wie häufig habe ich dich eigentlich schon beim Zeichnen dieses Diagramms gesehen?”, fragt er Ben.

Ben wird rot. “Ich mache das ein- bis zweimal im Monat", entgegnet er. "Immer, wenn wir einen neuen Praktikanten bekommen.”

Jim überschlägt in Gedanken, wieviel Zeit Ben dafür im Monat verwendet.

“Warum setzt ihr die Informationen nicht in ein Wiki?”, schlägt Michael vor und zeigt auf das Whiteboard. “Es würde euch enorm viel Zeit sparen. Ich könnte euch helfen, das Wiki aufzusetzen.”

checkmarkEine gute Architektur-Dokumentation …

  • abstrahiert die Kernfunktionen des Systems,
  • stellt alle Subsysteme vor,
  • zeigt das Zusammenwirken der Komponenten,
  • erklärt wichtige Konzepte,
  • visualisiert Softwareschichten.

Im Büro nebenan fährt Tony gerade seinen Rechner hoch. Seit Tagen versucht er, sich in ein neues Subsystem einzuarbeiten. Dessen Entwickler hat das Unternehmen letzte Woche verlassen. Er kannte das System in- und auswendig, machte sich aber nie die Mühe, es zu dokumentieren. Tony muss sich nun selbst ein Bild von dem Subsystem verschaffen, indem er Kollegen interviewt und den Code liest. Aber dabei verliert er wertvolle Zeit. Eigentlich hätte er längst die Anpassung einer Komponente abgeschlossen haben müssen.

checkmarkEine gute Low­-Level­-Dokumentation ...

  • hilft neuen Mitarbeitern sich in Subsysteme einzuarbeiten,
  • bündelt Fachwissen,
  • zeigt Schwachstellen des Systems auf,
  • stellt die Erweiterbarkeit des Systems sicher,
  • ist ein Kompromiss aus Detailstufe und Abstraktion für hohen Nutzwert und lange Gültigkeitsdauer,
  • wird in einem iterativen Entwicklungsprozess erstellt,
  • vermeidet Redundanzen durch modulare Strukturen,
  • befolgt Code Conventions und Developer Guidelines,
  • erklärt wichtige Begriffe in Glossaren.

Anna, Michael und Tony haben dasselbe Problem. Sie versuchen, ein System zu verstehen, das ihnen fremd ist oder das sie bisher nur aus einem anderen Blickwinkel betrachtet haben. Die Informationen, die ihnen zur Verfügung stehen, sind spärlich, oft veraltet, lückenhaft und redaktionell nicht aufbereitet. Wie das System wirklich funktioniert, steht oft nur im Code, den nicht jeder lesen kann oder darf.

Ihnen kann ein Redakteur helfen, der die verschiedenen Zielgruppen, die mit dem System arbeiten, ermittelt, der ihre Bedürfnisse in Erfahrung bringt und zusammen mit Entwicklern, Architekten und Managern Konzepte, Templates und Best Practices für die Dokumentation ausarbeitet. Technische Redakteure sind Experten bei der Auswahl der richtigen Dokumentationstypen und ­-prozesse, um den Fokus auf das Wesentliche zu legen und an den richtigen Stellen zu abstrahieren. Nur so bietet die Dokumentation einen hohen Nutzwert, kann schnell und kostengünstig erstellt werden und bleibt möglichst lange aktuell.

Je nach Projekt unterstützten Technische Redakteure die Entwicklingsteams aktiv bei der Erstellung der Dokumentation und stellen Qualität, Quantität und Konsistenz sicher. Als Teil des interdisziplinären Entwicklungsteams sind sie in den Entwicklungsprozess eingebunden und nehmen an Stand-Ups und Code-Reviews teil.

Gute Dokumentation bedeutet nicht, mehr Dokumentation zu erstellen. Es bedeutet, die richtige Dokumentation zu erstellen, um sie als wertvolles Informationsmedium nutzbar zu machen. Was “richtige Dokumentation” ausmacht, kann je nach Projekt unterschiedlich sein. Deswegen sind Dokumentationsprozesse niemals Standardlösungen, sondern individuell an die Bedürfnisse der Kunden angepasst. Sie müssen sich in die Unternehmensprozesse eingliedern. Nur so wird die Dokumentation vom notwendigen Übel zu einem wichtigen Instrument und bietet einen wertvollen Mehrwehrt.

Unser Wissensartikel Entwicklerdokumentation: das notwendige Übel? fasst unsere umfangreichen Erfahrungen aus unterschiedlichen Projekten zusammen. Er zeigt auf, was gute Entwicklerdokumentation ausmacht und beschreibt, wie man ein Softwaresystem gleichzeitig ausreichend und mit möglichst geringem Aufwand dokumentiert. Siehe zum gleichen Thema auch den Wissensartikel Documentation for Software Engineers.

Kommentar schreiben


  • facebook
  • linkedin
  • xing