Tipps für die technische Dokumentation // deutsch

Technische Dokumentation ist essenziell für nahezu jede Anwendung, doch kaum eine Entwicklerin oder ein Entwickler schreibt gerne Dokumentation. Allerdings haben die wenigsten Teams den Luxus, mit einer technischen Redakteurin oder einem technischen Redakteur zusammenzuarbeiten. Was gibt es beim Schreiben von technischer Dokumentation zu beachten, und wie lässt sie sich durchdacht strukturieren?

00:00 – Einleitung
00:55 – Zielgruppe definieren
02:19 – Vier Arten von Dokumentation
03:07 – Das Tutorial
04:16 – Die Konzeptdokumentation
06:02 – Das How-To
07:31 – Die Referenz
08:37 – Strukturen definieren
10:00 – Dokumentation aktualisieren
11:30 – Technische Basis

────────────────────

Über the native web 🦄

Wir sind ein Beratungs-, Schulungs- und Entwicklungsunternehmen, das sich auf Web- und Cloud-Technologien spezialisiert hat. Wir streben nach intelligenten und eleganten Lösungen für komplexe Probleme, und wir glauben, dass Softwareentwicklung kein Selbstzweck ist. Stattdessen sollte Software tatsächliche Probleme der realen Welt lösen.

Wir glauben, dass native Web- und Cloud-Technologien das Fundament sind, auf dem die Zukunft aufbaut. Unsere Kernkompetenz ist der Entwurf und die Entwicklung verteilter Web- und Cloud-Anwendungen unter Verwendung dieser Technologien in interdisziplinären Teams. Wir entwickeln auch unser eigenes Open-Source-Framework namens wolkenkit. Und wir lieben es, unser Wissen in Schulungen und Workshops, auf Konferenzen und bei Usergroups zu teilen.

────────────────────

Weiterführende Links 🌍

[optimeister]

Vielen Dank für das tolle Video! Die Tipps für die Herangehensweise an die Erstellung einer Doku sind vor allem für Technische Redakteure ohne allzu viel Erfahrung hilfreich. Wenn man die beherzigt und damit strukturiert sein Dokument aufbaut, seinen Anwender dabei immer im Blick hat und hier und da Leseanreize setzt, kann ein Manual richtig gut werden. Und das wirkt sich letztlich auch positiv auf die Kundenzufriedenheit mit dem gesamten Produkt aus.

[klausgrund]

Wow, jetzt bin ich geflasht! Schon seit einiger Zeit suche ich nach Ideen, wie ich eine Dokumentation der Arbeiten für meine Kunden erstellen kann. Schließlich möchte ich, wenn ich mal meine Selbständigkeit aufgebe, keine verbrannte Erde hinterlassen. Genau dieses Video hat den Schalter in meinem Kopf umgelegt, denn nun weiß ich, wie ich meine Doku strukturiere. Vom Schreibaufwand her gesehen natürlcih enorm, aber mit einleuchtender Struktur, die mir selbst und meinen Kunden helfen wird. Super und Danke, Danke, Danke. Soweit zum Inhaltlichen.

Die Präsentation ließ auch keine Wünsche offen. Verständlich, freundlich, angenehmes Tempo. Besser geht nicht. Auch hier ein dickes Dankeschön.

[kvnx]

Super Video speziell weil Dokumentation oft zu kurz kommt obwohl sie so wichtig ist gerade bei neuen Mitarbeitern oder wenn das Ursprungsteam vielleicht nicht mehr im Unternehmen ist.

[oliverabrahamhamburg]

Sehr interessantes Thema, danke für die guten Erklärungen! Vielfach wird es vernachlässigt. Ich möchte ein paar Dinge dazu beitragen: 1.Das Softwaredesign bestimmt maßgeblich die Dokumentation. Wenn Software schon selbsterklärend ist, braucht es weniger Dokumentation. In früheren Projekten mussten wir in der Doku Codes erklären, frei nach dem Motto "für die Neuanlage tragen sie hier eine 1 ein". Das Beispiel ist etwas übertrieben, aber ihr versteht? Gute Software spart Doku und Hotline. 2.Stichwort Desktop GUI-Design: Denkt daran, dass Labels in Fremdsprachen teilweise mehr Platz brauchen. Steht die Übersetzung von Englisch auf Französisch an, ist öfter eine Überarbeitung der GUI nötig. Die GUI sollte wenn möglich responsive sein. 3.Der Weg vom Programmcode zur Doku sollte kurz sein. Vielleicht kann man die Kapitel als separate Textdateien speichern und gleich mit dem Programmcode einchecken. Beispiel: Wenn ich Code ändere, passe ich Unit tests an, und auch gleich die Doku. Ein Commit. Das Handbuch könnte man aus den einzelnen Dateien generieren.

[nasenbar]

Wow, habs noch gar nicht gesehen, aber gehe mal davon aus, dass es gut ist, hab schon mehr von euch gesehen. Schade, dass ich das nicht schon früher entdeckt habe, hab meine Doku leider schon abgegeben (für Fachinformatiker Anwendungsentwicklung)

[bsdooby]

Ja, Grammatik ist sehr wichtig. Repräsentiert die Applikation resp. den Hersteller (Visitenkarte). Eine weitere Problematik von (API) Dokumentation: Sie skaliert nicht mit dem Code, und sie ist häufig redundant.

[MarkusEicher]

Grüss dich Golo. Wie von euch gewohnt, sehr hilfreich, danke! Ich habe viel Erfahrung mit dem Schreiben von Dokumentationen im IT Infrastruktur Umfeld, allerdings keine im Bereich der für mich noch neuen Software Entwicklung. Die 4 Typen sind jedoch identisch in beiden Domänen. Sind ja auch verwandt. Du schreibst unten, dass ihr intern Markdown verwendet und eine React-App zum rendern. Find ich sehr interessant. Dazu aber die Frage, wie macht ihr das, wenn die Doku ausgedruckt werden muss? Ist es nicht mühsam diese dann entsprechend zu formatieren? Habt ein schönes Wochenende. 🍀

[krccmsitp]

Für technische Dokumentation orientieren wir uns gerne an arc42. Meist schreiben wir alles in Markdown, Code und zugehörige Doku werden dann auch gemeinsam versioniert (VCS).

[MoonShadeStuff]

Wir wollten mal Antora als technische Basis für die Dokumentation von Microfrontends evaluieren, da er sich Asciidoc files aus mehreren Repos zieht und eine gemeinschaftliche Doku erstellt die man dann veröffentlichen kann. Gibt’s da zufällig Erfahrungswerte?

[plus]

Keine Dokumentation ist auch eine Dokumentation.

[medinkrupic]

Bitte weniger die Hände bewegen und den Kopf etwas senken .