Alles beginnt mit dem ersten Schritt: Einstieg in die Softwaredokumentation

Jede Reise beginnt mit dem ersten Schritt – das gilt auch für den Dokumentationsprozess einer Software. Neben der Beratung durch einen professionellen Dienstleister, können Sie auch vorab in Eigenregie starten, interne Prozesse zu etablieren. Dazu gehören relevante Tätigkeiten und die sich daraus ergebenden Rollen der Nutzenden zu ermitteln. Zudem muss die Nutzungsgruppe analysiert und Rückschlüsse auf die Bedürfnisse an die Dokumentation gezogen werden. Der Erstellungsprozess samt Softwareauswahl, Struktur und Inhalt, wirft weitere Fragen auf.

Sie möchten erste Schritte für die Organisation Ihrer Technischen Redaktion selbst angehen? Für Sie haben wir einige Basics rund um das Thema Informationsprodukte in der Softwarebranche für den Einstieg zusammengefasst.

Wer sollte Software dokumentieren?

Die Antwort ist einfach: Eine kompetente, dafür ausgebildete Person!

Das ist meist nicht der Entwickler, sondern ein Technischer Redakteur oder eine Technische Redakteurin. Diese wurden dafür ausgebildet. Ihnen bereiten diese Arbeiten Spaß – ganz im Gegensatz zu den meisten Entwicklern und anderen IT-Mitarbeitern.

Sollten Sie dafür kein kompetentes Teammitglied in Ihren Reihen haben, bietet sich die Unterstützung durch einen Dokumentationsdienstleister an. Profitieren Sie von unserer Begeisterung in der Informationserfassung.

Zudem ist Dokumentieren eine Daueraufgabe. Diese muss folglich immer ausreichend und parallel zum eigentlichen Entwicklungsprozess der Software erfolgen und nicht erst knapp und unvollständig nach Abschluss des Projekts. Sorgen Sie dafür, dass die Dokumentation Bestandteil der eigentlichen Entwicklungsarbeit wird. Heißt, das Dokumentationsteam muss in den Entwicklungsprozess durch z. B. die regelmäßige Teilnahme an Jour Fixe Terminen eingebunden werden.

Möchten Sie diese Aufgaben outsourcen? Setzen Sie auf unsere Experten, um Ihren Dokumentationsprozess in die Entwicklungsarbeit zu integrieren, einzelne Informationsprodukte zu übernehmen oder für den nötigen Feinschliff Ihrer selbst erstellten Dokumentationen zu sorgen.

Wie fängt man mit einer Dokumentenstruktur an?

Zunächst muss die Struktur festgelegt werden. Wir folgen dem Ansatz des Single-Source-Publishings. Layout-neutral erstellte Informationsprodukte können in alle Medien und Formate publiziert werden und sind je nach Anforderungen der Anwendung, des eingesetzten Mediums und des Formats unterschiedlich darstellbar.

Weiter haben Sie mit dieser Arbeitsweise den Vorteil, dass Sie sich voll und ganz auf den Inhalt Ihrer Texte konzentrieren können und Duplikate sowie dadurch entstehende veraltete Informationssilos vermeiden.

Doch wie fängt man überhaupt mit dem Dokumentieren an? Unsere Checkliste liefert Ihnen dazu einen ersten Einstieg:

• Verantwortlichkeiten im Team klären
• Projektanforderungen ermitteln und vermitteln
• Zielgruppen beschreiben
• Informationsprodukte festlegen
• Ausgabemedium und -format pro Informationsprodukt definieren
• Informationsrecherche betreiben
• Inhaltsverzeichnis festlegen
• Inhalte erstellen
• Qualität der Inhalte überprüfen (sprachlich, fachlich, technisch)
• Inhalte publizieren
• Inhalte pflegen

Was sollte dokumentiert werden?

Aus vielen Gesprächen kristallisieren sich immer wieder dieselben Fragen heraus. Finden auch Sie sich in einer der Situationen wieder?

„Wir haben das Gefühl, wir dokumentieren nicht das richtige.“

„Unsere Dokumentation wird nicht gelesen und wir beschreiben viel zu viel.“

„Wir kommen mit dem Erstellen der Dokumentation nicht hinterher.“

Um den Ursachen der oben beschriebenen Situationen auf den Zahn zu fühlen, Konzepte zu entwickeln, die den Ursachen entgegenwirken und herauszufinden, ob sich das Dokumentieren auch lohnt, haben wir einen Tipp für Sie:

Dokumentieren Sie immer dann, wenn es:

• um Wissen geht, das langfristig interessant ist und
• um Wissen geht, das für viele Personen interessant ist.

Sie sollten nicht dokumentieren, wenn:

• das Wissen morgen bereits veraltet ist und Ihr Produkt nur sekundär betrifft.
  Diese Informationen haben keine hohe Priorität.
• das Wissen nur eine Person interessiert.
  Gibt es keine breitere Zielgruppe für die Informationen, sind diese nicht primär für Informationsprodukte relevant.

Ist Ihre Dokumentation nicht aktuell, hat sie keinen Mehrwert, sie ist nicht nützlich. Ist das Vertrauen in die Korrektheit und die Aktualität Ihrer Informationen dahin, wird es schwer, dieses Vertrauen bei der Leserschaft wieder aufzubauen.

Ihre Software- bzw. IT-Dokumentation sollte daher folgende Kriterien erfüllen:

• exakt im Wortlaut
• verlässlich in Bezug auf die Aktualität
• synchron zum ausgelieferten Entwicklungsstand
• kollaborativ, denn sie fördert den Wissensaustausch zwischen Personen
• erkenntnisreich, weil durchdacht und in mehreren Iterationen abgestimmt
• zugänglich, durchsuchbar und barrierefrei

Oft lohnt es sich, einen neutralen Blick zu bekommen. Sprechen Sie mit uns, wenn es um die Frage geht, was in Ihrem konkreten Fall nun dokumentiert werden soll.

So gehen wir vor – hier können Sie Rückschlüsse für Ihr eigenes Vorgehen ziehen!

Unsere standardisierte Planung hilft dabei, die IT-Prozesse, das Produkt, den IST-Zustand und den Bedarf an die interne IT-Dokumentation zu klären. Diese Recherche erfolgt in partnerschaftlicher Zusammenarbeit mit Ihren Fachabteilungen.

Wir entwickeln ein Konzept, das nicht nur dabei hilft, das digitale Produkt zu beschreiben, sondern auch ermöglicht, die Funktionsweisen und Aufgaben der Nutzenden des digitalen Produktes innerhalb von ganzheitlichen Geschäftsprozessen zu betrachten und zu dokumentieren. Für die Nutzungsrecherche bedienen wir uns unserer Cross-Domain-Expertise in der User Experience und wenden die dortigen Research-Methoden in der Praxis an.

Nach Klärung der Frage, welche Informationsprodukte von wem und in welchem Zeitintervall gepflegt werden, sind ein perfekt funktionierendes Dateiablagesystem und eine saubere Versionskontrolle essentielle Pfeiler eines guten Dokumentationskonzepts. Das Ergebnis unserer Arbeit ist Ihr Dokumentationsleitfaden, der die zu entstehenden Dokumente und den Weg zum Ziel standardisiert. Ein Dokumentationsflow, der wie maßgeschneidert sitzt!

Bei Bedarf beraten wir Sie gerne auch bei der Abwägung, der Einführung und Pflege eines Content-Management-Systems.