#125 Die Kunst der technischen Dokumentation mit Jana Aydinbas

Dokumentation: Jeder braucht sie, keiner will sie schreiben

Vielen Software-Entwickler⋅innen ist eins nicht bewusst: Technisches Schreiben ist eine Profession. Ein eigener Beruf. Denn es ist eine Kunst, Dokumentation so zu schreiben, dass sie auch gelesen und genutzt wird. Die Kunst, komplexe technische Informationen schnell zugänglich zu machen.

Doch wie macht man das denn nun genau? Darüber sprechen wir mit Jana Aydinbas. Jana ist von Beruf Technical Writerin. Wir klären die Unterschiede zwischen Technical Writing und normalem schreiben, geben Einblick in das Berufsfeld, widerlegen klassische Mythen die Software-Entwickler⋅innen gegenüber dem Schreiben von Dokumentation haben, und lassen uns erklären, was eigentlich eine gute und professionelle Dokumentation ausmacht und wie man selbst den eigenen Doku-Skill verbessern kann.

Bonus: Jira Tickets lesen ist gleichzusetzen mit investigativem Journalismus

Das schnelle Feedback zur Episode:

👍 (top) 👎 (geht so)

Sprungmarken

(00:00:00) Technical Writing mit Jana

(00:04:26) Dokumentation schreiben, aber Hauptberuflich: Warum?

(00:05:51) Technical Writing, normalem Schreiben und Redakteure und

(00:09:17) Jira-Research und Dokumentation im Software Development Lifecycle

(00:14:21) In eigener Sache

(00:15:16) Jira-Research und Dokumentation im Software Development Lifecycle

(00:20:35) Was macht eine Dokumentation zu einer guten Dokumentation? (Regeln, Zielgruppe, Terminologie)

(00:27:02) Übersetzungen, Code, Screenshots in Dokumentationen und AI

(00:35:23) Dokumentations-Mythen: Out of Date, niemand liest Dokumentation, Dokumentation schreiben ist nicht attraktiv, Code ist die Dokumentation

(00:44:16) Dokumentation für Hardware

(00:47:31) Dokumentation im Open Source Bereich

(00:50:54) Read the docs und Write the docs

(00:53:37) Dokumentations-Best-Practices zum selber anwenden

Hosts

Wolfgang Gassler (https://mastodon.social/@woolf)
Andy Grunwald (https://twitter.com/andygrunwald)

Feedback

EngKiosk Community: https://engineeringkiosk.dev/join-discord
Buy us a coffee: https://www.buymeacoffee.com/engineeringkiosk
Email: stehtisch@engineeringkiosk.dev
LinkedIn: https://www.linkedin.com/company/engineering-kiosk/
Mastodon: https://podcasts.social/@engkiosk
Twitter: https://twitter.com/EngKiosk

Transkript

Das Transkript wurde automatisiert per Speech-to-Text erstellt und kann daher Fehler enthalten.

Andy Grunwald (00:00:03 - 00:01:07)

Es lohnt sich doch gar nicht, Dokumentation zu schreiben. Die ist doch sofort wieder out of date. Niemand, aber auch wirklich niemand liest meine Dokumentation. Der Code, der Code ist die wahre Dokumentation. Das oder so ähnlich sind die Standardausreden, die ich im Laufe der Jahre gehört habe, warum man selbst keine Dokumentation schreiben möchte. Dreht man den Spieß aber mal um, braucht jeder von uns aber eine Dokumentation, um überhaupt mit der Software arbeiten zu können. Das Schreiben einer guten Dokumentation ist somit eine Arbeit mit einem sehr hohen Impact und kann unter Umständen die ganze Firma enablen. Doch wer weiß denn schon, wann eine Dokumentation eine gute Dokumentation ist? Diese Antwort ist Personen, die Dokumentation im professionellen Umfeld schreiben und damit ihr Geld verdienen. In dieser Episode sprechen wir mit Jana, einer Technical Writerin. Mit ihr klären wir die Unterschiede zwischen Technical Writing und normalem Schreiben, geben Einblicke in das Berufsfeld des technischen Schreibens und schauen mal, was eine gute Dokumentation eigentlich so gut macht. Und wenn du deine Doku skills deutlich verbessern möchtest, solltest du dranbleiben. Wir zappeln nicht lange. Los geht's.

Jana Aydinbas (00:01:07 - 00:01:08)

Viel Spaß.

Wolfi Gassler (00:01:10 - 00:01:17)

Andi, ich möchte mal mit einer kurzen Geschichte starten. Und wenn ich Geschichten erzähle, dann spielt sich das in was für einem Bereich immer ab?

Andy Grunwald (00:01:17 - 00:01:29)

Entweder hat das was mit Wandern zu tun oder irgendwelchen Skitouren auf Bergen oder oder es dreht sich irgendwie um die freiwillige Feuerwehr. Aber da legst du ganz viel Wert darauf, dass eure freiwillige Feuerwehr nicht immer Alkohol trinkt.

Wolfi Gassler (00:01:29 - 00:02:44)

Korrekt? Du hast es sehr gut erkannt. Aber in dem Fall ist es wirklich eine Feuerwehr Story. Und zwar habe ich kürzlich Ausschau gehalten nach einer Software für die Feuerwehr, so eine Alarmierungssoftware. Und ich habe da eine ganz kleine Software gefunden und war mir nicht sicher. Hat eigentlich wenige Informationen auf der Landingpage gehabt, hat aber eigentlich genau das gemacht, was wir gesucht haben. Dann bin ich zufällig auf die Dokumentation gestoßen. Das mache ich eigentlich ganz gern, mal zu schauen, wie gut das dokumentiert ist, was es an Informationen und Hilfe gibt. Gerade bei so kleineren Projekten ist das ja oft ein Problem. Und in dem Fall war die Dokumentation wirklich sehr gut, also schön aufbereitet, irgendwie, ich glaube mit Retype oder so gemacht. Und es waren jetzt nicht extrem viele Informationen, aber es waren zumindest die richtigen Informationen und genau die Informationen, die ich noch gesucht habe. Und für mich ist das eigentlich so ein Qualitätsmerkmal, würde ich fast sagen, wenn eine Software gute Dokumentation hat. Und mittlerweile habe ich die Software jetzt schon einige Zeit in Verwendung und es hat sich bewahrheitet, es ist wirklich auch die Software gut. Also man könnte ja fast sagen, dass eine gute Dokumentation auch auf eine gute Softwarequalität schließen lässt. Und genau darum möchte ich auch in diesem Podcast bzw. In dieser Episode mal tiefer eintauchen in das ganze Dokumentationsthema.

Andy Grunwald (00:02:44 - 00:02:46)

Was ist Retype?

Wolfi Gassler (00:02:46 - 00:02:53)

Das können wir jetzt gleich unseren Gast fragen. Willkommen Jana. Hast du zufällig eine Ahnung, was Retype ist?

Jana Aydinbas (00:02:53 - 00:02:55)

Nein, ich habe mir hier dieselbe Frage gestellt.

Wolfi Gassler (00:02:55 - 00:03:25)

Ja, jetzt bin ich natürlich in Erklärungsnot. Es war so Bild bei Retype oder mit Retype. Ich glaube, es ist einfach ein schönes Framework, um eine Dokumentation zu erstellen. Aber ehrlich gesagt, ich bin mir jetzt auch nicht sicher, ob es irgendein Open Source Tool ist oder irgendein Managed Framework. Keine Ahnung. Aber es ist scheint auf jeden Fall eine schöne Dokumentation auszuspucken aus irgendwelchen Markt falls oder sowas in der Richtung. Aber eigentlich geht es heute um die Dokumentation bzw. Noch tiefergehend über die Profession Technical Writer.

Andy Grunwald (00:03:25 - 00:03:51)

Und dafür dürfen wir Jana begrüßen. Hallo, vielen lieben Dank, dass du dir die Zeit genommen hast, um mit uns über dieses Thema zu sprechen. Jana, bevor wir in das Thema, in dein Lieblingsthema einsteigen und jetzt auch mein Lieblingsthema, auch Wolfgangs Lieblingsthema und anscheinend von der freiwilligen Feuerwehr von Innsbruck das Lieblingsthema. Jana, wer bist du? Du kommst aus dem Süden, zumindest aus meiner Perspektive, aus Karlsruhe, aus Baden Württemberg.

Wolfi Gassler (00:03:51 - 00:03:54)

Mein Norden, Wolfgangs Norden.

Andy Grunwald (00:03:54 - 00:04:22)

Du hast einen Bachelor of arts in Bibliotheks und Informationsmanagement, was auch themenrelevant ist in der Hinsicht. Ein Master of Science hast du in Technical Communication an der Hochschule in Karlsruhe gemacht. Du arbeitest als Technical Writer im Bereich Softwaredokumentation und du warst bis vor kurzem sogar sehr, sehr starkes Community Mitglied, weil du die Co Organisatorin des Ride the Docs Karlsruhe Mieter warst. Stimmt das alles?

Jana Aydinbas (00:04:22 - 00:04:26)

Ja, das ist alles korrekt. Ich freue mich, hier zu sein und mit euch über Dokumentation zu sprechen.

Wolfi Gassler (00:04:26 - 00:04:48)

Jetzt gleich meine initiale Frage, weil wir sind ja beide Softwareentwickler in dem Fall. Und was man ja so von Softwareentwicklerinnen immer hört, ist, dass eigentlich diese Dokumentation ja eher nicht so gern geschrieben wird. Und alle kennen das. Man muss am Ende, wo man noch irgendwie Dokumentation schreiben hat, keine Lust. Du machst es hauptberuflich. Warum?

Jana Aydinbas (00:04:48 - 00:05:02)

Ich mache das hauptberuflich und mit Freude. Ich mag das, so einen Berg an Informationen zusammenzutragen und dann durchzuwühlen, auszusortieren, Informationen zu gruppieren und umzustrukturieren. Und dann am Ende kommt hoffentlich was bei raus, was anderen Menschen hilft.

Andy Grunwald (00:05:02 - 00:05:22)

Ja, also ich meine, im Endeffekt hat der Wolfgang ja den Beweis angetreten. Anscheinend hat eine Dokumentation ihn sogar zum Kauf einer Software, wie soll man sagen, ja, befähigt, weiß ich nicht. Auf jeden Fall war das der Entscheidungsfaktor. Habe ich aber so auch noch nicht gehört, dass die Dokumentation ein Entscheidungsfaktor ist. Aber da lasse ich mich gerne auch noch mal des Besseren belehren.

Wolfi Gassler (00:05:22 - 00:05:43)

Das Schöne ist ja, dass man dort eigentlich Informationen lesen kann, die nicht auf der klassischen Marketing Webseite stehen, weil die Marketing Website ist halt immer so Marketing blabla Bullshit und auf der Dokumentationsseite siehst du sofort irgendwie, was gibt es, was sind für APIs verfügbar, wie funktioniert was? Man findet vielleicht sogar so ein bisschen user Experience und das finde ich eigentlich immer super interessant.

Jana Aydinbas (00:05:43 - 00:05:47)

Ein gutes Beispiel dafür, dass Dokumentation auch ein Alleinstellungsmerkmal sein kann.

Wolfi Gassler (00:05:47 - 00:05:50)

Aber Andy schreibt scheinbar auch nicht gerne Dokumentation.

Andy Grunwald (00:05:51 - 00:06:41)

Schwierige Thematik, weil ich habe immer so, ich glaube, ich überdenke das Thema von Dokumentation, aber da kommen wir, da kommen wir gleich auch noch mal drauf zu. Aber jetzt habe ich ja den Standpunkt in diesem Podcast über mehrere Episoden, dass ich, dass ich die Kunst des Schreibens wirklich liebe. Ich denke, Schreiben ist natürlich tolle Geschichte. Theoretisch müsste ich auch Fan sein von Dokumentation schreiben und auf Instagram sieht man ja auch immer alle Leute sollen Journaling machen und einfach mal morgens schreiben. Aber ich meine Dokumentation schreiben ist ja schon mal ein bisschen was anderes als wenn ich jetzt in Harry Potter schreibe. Deswegen Jana, erklär uns doch mal bitte, was ist eigentlich der Unterschied zwischen, ich sag mal technischem Schreiben oder ist die deutsche Übersetzung zu technischen Schreiben technical writing? Ich glaube schon gegenüber dem Schreiben, was jetzt Jaker Rowling mit Harry Potter macht.

Jana Aydinbas (00:06:41 - 00:06:59)

Genau, technical writing kann man ganz grob einteilen unter Non Fiction Writing. Deswegen würde ich sagen, ist es tatsächlich nicht wie Harry Potter schreiben, was eher an den Fiction Writing fallen würde, weil es geht nicht um kreatives Schreiben, sondern es geht eher um standardisiertes, regelbasiertes Schreiben.

Andy Grunwald (00:06:59 - 00:07:07)

Aber wenn du jetzt von Regeln sprichst, dann sprechen wir jetzt nicht von Grammatik auch, aber ich meine, die Regeln hat man doch auch beim Fiction Schreiben, oder?

Jana Aydinbas (00:07:07 - 00:07:31)

Ja, also das wäre eine Gemeinsamkeit, dass man Rechtschreibung und Grammatik einer Sprache verwendet, weil sich beides natürlicher Sprache bedient. Aber z.b. eine Grobstruktur von Informationen oder ein Satzaufbau, dass terminologiekonsistent verwendet werden müsste, das wären Unterschiede, weil technische Dokumentation soll nicht primär unterhalten.

Andy Grunwald (00:07:31 - 00:07:36)

Z.B. ja, also ich meine ich komme aus dem Ruhrgebiet, deswegen ich habe von Natur aus Probleme schon auch so mit.

Wolfi Gassler (00:07:36 - 00:07:38)

Dem Satzaufbau, das kann ich dir zeigen.

Andy Grunwald (00:07:39 - 00:07:55)

Nun gut, aber jetzt ist es so, wenn ich nicht weiß was was technical writing ist, dann gebe ich bei Google den Begriff ein, komme auf Wikipedia und lese mir den ersten Paragraphen durch. Also wie würdest du jetzt den Beruf definieren? Wie würdest du mir diese professionelle beschreiben?

Wolfi Gassler (00:07:55 - 00:08:03)

Gibt es da übrigens einen deutschen Begriff dafür? Weil wir werden ja immer geschumpfen, dass wir immer so viele englische Begriffe erwähnen bei uns im Podcast.

Jana Aydinbas (00:08:03 - 00:08:41)

Ja, die deutsche Entsprechung wäre technische Redakteurin. Und was wir machen, wird oft abstrahiert bezeichnet als wir machen komplexe technische Informationen für die Zielgruppe eines Produkts verständlich. Und das wird sehr allgemein gehalten. Bei der Agentur für Arbeit liest man z.b. auch, dass technische Redakteure und Redakteuren umsetzbare, verständliche technische Beschreibung aller Art erstellen. Und das einfach so abstrakt, weil wir so viele Informationsprodukte damit abdecken. Seien es jetzt Onlinehilfen oder gedruckte Bedienungsanleitungen oder eine anleitende App. Es kann alles mögliche sein.

Andy Grunwald (00:08:41 - 00:08:57)

Und jetzt hast du schon den Begriff des Redakteurs ins Spiel gebracht. Und immer wenn ich denke Redakteur, dann denke ich irgendwie an Journalismus, dann denke ich irgendwie an, ich sage jetzt mal ganz doof, die Computerbild oder die CT oder das Java Magazin. Ist das irgendwie, ich sag mal, das Gleiche, oder?

Jana Aydinbas (00:08:57 - 00:09:17)

Also es fällt beides in die Kategorie Non Fiction. Es sind schon gewisse Gemeinsamkeiten vorhanden, aber auch Unterschiede. Ich glaube, bei Technik Zeitschriften geht es eher um journalistisches Schreiben, was die Textarten und Inhalte angeht. Da ist Technical Writing im Sinne von Online Hilfen schreiben beispielsweise doch noch was anderes.

Wolfi Gassler (00:09:17 - 00:09:35)

Wenn man das jetzt vergleicht, so Journalistinnen verbringen ja recht viel Zeit in der Recherche, bevor sie überhaupt dann was schreiben. Würdest du sagen, das ist bei dir anders? Oder in was für einem Prozentsatz verhält sich das so zwischen Recherche und dann wirklich konkretes Aufschreiben, Sätze kreieren?

Jana Aydinbas (00:09:35 - 00:10:12)

Das ist ein guter Punkt. Das wäre eine der Gemeinsamkeiten. Ich würde sagen, 80 % meines Berufsalltags bestehen aus Recherche. Das kann Jira Recherche sein, wo ich mich selbst quasi bediene an Informationen in einem System oder ich spreche mit Entwickler innen. Deswegen Die Berufsbezeichnung Technical Writer in ist ein bisschen irreführend. Es geht ja nicht nur ums Schreiben, sondern auch um Konzeption, um Terminologiearbeit, um vielleicht auch Grafiken und Screenshots. Das Ganze muss reviewed werden, getestet und dann wird ja nicht nur von null aufgeschrieben, sondern ganz viel editiert, was schon vorhanden ist.

Wolfi Gassler (00:10:12 - 00:10:21)

Und das musst du dir alles selber zusammensuchen oder bekommst du da dann Input auch von irgendwelchen Entwicklerinnen? Oder wie läuft denn das so grob ab?

Jana Aydinbas (00:10:21 - 00:10:41)

Sowohl als auch. Ich bin Teil eines agilen Entwicklungsprozesses bei mir im Unternehmen. Das heißt, ich nehme an Scrum Events teil, die für mich quasi Recherchetermine sind. Ich habe eins zu eins Kontakt zu Entwicklerinnen, POS etc. Und ich stelle gezielt fragen, wenn ich Informationen brauche.

Wolfi Gassler (00:10:41 - 00:10:53)

Das heißt aber, du bist dann wirklich schon im Scrum Team frühzeitig eingebunden. Es ist nicht so, alles wird irgendwie fertig gemacht und dann kommst du ins Spiel, sondern du bist ja schon im Scrum, Dailies oder solchen Dingen eingebunden.

Jana Aydinbas (00:10:53 - 00:11:15)

Genau, der Produktentstehungsprozess ist nicht abgelaufen und ich muss hinterher mir noch eine Doku aus den Ärmeln schütteln. Jetzt nicht, sondern ich bin schon bei Storytime, heißt es bei uns, und beim Refinement dabei. Ich weiß also schon, was quasi an Funktionen implementiert wird, was mich da erwartet. Ich bin bei den Dailies dabei, ich bin Teil eines interdisziplinären Scrum Teams.

Andy Grunwald (00:11:15 - 00:11:34)

Gerade bei dem Begriff Jira Recherche, schuld unterbreche ich muss nämlich immer so lachen, sonst komme ich da nicht raus. Jira Recherche, ich weiß ja ungefähr, wie die Jira Hygiene in diversen Firmen ist. Und dann stelle ich mir gerade die Frage, ob das nicht schon wieder investigativer Journalismus ist, sich so wie als Jira zu kämpfen. Aber nun gut, Scherz beiseite. Wolfgang, du wolltest gerade irgendwas fragen, tut mir leid.

Wolfi Gassler (00:11:35 - 00:11:59)

Ja, ich wollte eigentlich nur. Beim Scrum Team ist es ja z.B. bei Designer und Designerinnen ist es ja immer so eine Frage, kann ich irgendwie eine dedicated person in meinem Team haben zu design oder zu, keine Ahnung, QA oder so irgendwas. Wie ist es bei euch? Hast du dann irgendwie 10 Teams oder wie kann man sich das vorstellen? Weil ich schätze mal, du bist nicht nur für ein Team verantwortlich dann am Ende, oder?

Jana Aydinbas (00:11:59 - 00:12:07)

Genau, bei uns sind es nicht 10 Teams, aber zwei. Ich bin in zwei Teams und die unterstütze ich mit der Dokumentationserstellung.

Andy Grunwald (00:12:07 - 00:12:14)

Die zwei Teams aber arbeiten aber am selben Produkt oder sind das zwei unterschiedliche Produkte? Also hast du dann diese Kontext Switche die ganze Zeit?

Jana Aydinbas (00:12:15 - 00:12:21)

Ja, am selben Produkt, aber an unterschiedlichen Teilbereichen. Ich habe tatsächlich Kontext Switche.

Andy Grunwald (00:12:22 - 00:12:32)

Kann ich mir das so vorstellen, wie als wenn man zwischen zwei Programmiersprachen springt? Weil ich finde, das ist unglaublich ermüdend. Oder sagst du, okay, du hast den Montag für Team eins und den Dienstag für Team zweite?

Jana Aydinbas (00:12:33 - 00:12:42)

Nee, das nicht. In einem zwei Wochen Sprint gibt es keine Wechseltage bei meinen Teams. Ich bin bei allem parallel dabei und ich muss mir meine Zeit einteilen, so wie es geht.

Wolfi Gassler (00:12:42 - 00:13:03)

Jetzt hast du ja auch ein bisschen mehr Einblick, auch über Meetup und diverse Gruppen. Ist es meistens so, dass man da wirklich Personen im Unternehmen hat, die Technical Writing machen oder wird sowas auch outgesourced oder ist es eher, muss man eine gewisse Größe haben als Unternehmen, dass man sich sowas unter Anführungszeichen irgendwie auch leistet dann schlussendlich?

Jana Aydinbas (00:13:03 - 00:13:36)

Es gibt eigentlich alle Modelle. Also es gibt Dienstleistungsunternehmen und ich hatte meinen Einstieg ins Technical Writing bei einem es gibt Unternehmen, die eine eigene technische Redaktionsabteilung haben, es gibt quasi Consulting Unternehmen, die das als Dienstleistung anbieten, Freelancerinnen aus dem Bereich Technical Writing, ganz unterschiedlich. Und jedes Unternehmen muss selbst bestimmen, wie viel Wert es auf Technical Writing legt und wie speziell auch die Anforderungen sind und ob die erfüllt werden können von den entsprechenden Rollen.

Andy Grunwald (00:13:36 - 00:13:56)

Aber wie funktioniert das denn mit der Informationsübergabe, wenn man als Dienstleistungsunternehmen da agiert? Ich meine, du hast ja gesagt, du machst ziemlich viel, ich nenne das jetzt investigativen Journalismus im Jira und du hast jetzt Kontakt zu den Leuten, die die Software schreiben. Aber wenn das eine Dienstleistung ist, dann stelle ich mir das vor wie so ein Steuerberater, wo man dann die Rechnungen übergibt, oder?

Jana Aydinbas (00:13:57 - 00:14:21)

Ja, es war wirklich ein anderes Arbeiten beim Dienstleistungsunternehmen. Wir haben ein projektbasiert mit Kunden zusammengearbeitet und die haben schon Pakete geschnürt, die abgearbeitet werden mussten. Das waren meistens Unternehmen, die hatten schon technische Redakteur innen und die wussten also, wie man mit denen zusammenarbeitet, welche Informationen die brauchen und konnten sich entsprechend vorbereiten. Und die waren einfach so ausgelastet, dass sie zusätzliche Unterstützung gebraucht haben.

Wolfi Gassler (00:15:16 - 00:15:46)

Aber wenn wir noch mal zurückkommen auf das Scrum Team und auf den Arbeitsablauf, der würde mir eigentlich auch sehr interessieren, wie du da im Team zusammenarbeitest. Holst du dir da selber deine Aufgaben? Werfen dir die Entwicklerinnen die hin? Schreiben die selbst überhaupt noch Dokumentation, übernimmst das hundertprozentig du? Also wie ist da die Zusammenarbeit? Ihr könnt mir ja vorstellen, dass die alle total happy sind, weil die Jana liebt Dokumentation, also macht hundertprozentig der Dokumentation die Jana. Und ich brauche als Entwickler gar nichts mehr machen.

Jana Aydinbas (00:15:46 - 00:16:11)

Sowohl als auch. Also z.b. so was wie Entwicklerdokumentation schreibe ich nicht, wo Entwickler innen irgendwelche Prozesse z.B. dokumentieren, die intern gemacht werden. Ich schreibe beispielsweise an einer Online Hilfe, ich schreibe bei den Release Notes mit, solche Dinge. Und es ist eine Zusammenarbeit. Also die Entwickler schreiben die Release Notes vor und ich mache den Feinschliff.

Wolfi Gassler (00:16:12 - 00:16:21)

Das heißt, du bist vor allem für außen verantwortlich, also für den Kontakt zur Außenwelt, zu den Usern im Normalfall höchstwahrscheinlich, oder?

Jana Aydinbas (00:16:21 - 00:16:21)

Richtig, ja.

Wolfi Gassler (00:16:22 - 00:16:37)

Und wie weit hast du Kontakt mit den Usern? Gibt es da auch irgendwie eine Beziehung oder ist das für dich ein schwarzes Loch und du wirst da einfach Dokumentation nach außen und hoffentlich wird das irgendwie konsumiert?

Jana Aydinbas (00:16:37 - 00:17:17)

Leider habe ich wenig Kontakt und auch wenig Feedback. Manchmal ist es frustrierend, weil man so im luftleeren Raum arbeitet und gar nicht weiß, kommt was an, wird es genutzt, ist es das, was benötigt wird? Also ideal wäre, dass man sich Feedback einholen kann bei den Nutzer innen, aber bei uns geht es z.b. technisch nicht. Wir liefern die Doku mit einem System aus und die läuft auf der Kundeninfrastruktur und dann kann man beispielsweise auch keine Metriken erheben, weil es technisch nicht möglich ist. Aber es gibt die Möglichkeit, Feedback zu geben. Wir haben ein Doku Postfach, wo sich Kundinnen auch an uns wenden können, gezielt mit Fragen zur Dokumentation und Feedback und.

Wolfi Gassler (00:17:17 - 00:17:19)

Wie viel kommt da wirklich zurück?

Jana Aydinbas (00:17:19 - 00:17:22)

Hin und wieder kommt was, aber du.

Wolfi Gassler (00:17:22 - 00:17:30)

Arbeitest jetzt schon bei einer großen Firma mit einer großen Userbase, also ist das wahrscheinlich ein wahnsinnig kleiner Prozentsatz, wo da irgendwas zurückfließt, oder? Kann ich mir vorstellen.

Jana Aydinbas (00:17:30 - 00:17:38)

Ich bin noch recht neu im Unternehmen, aber ich persönlich habe noch kein Feedback bekommen, aber ich weiß von Kolleg innen, die welches bekommen haben.

Wolfi Gassler (00:17:38 - 00:18:06)

Das nächste ist ja auch, dass so Metriken eigentlich auch immer gefährlich sind, weil wenn jetzt theoretisch z.B. gemessen wird, wie viel User und wie viel Traffic auf der Dokumentation ist, es kann ja auch nur ein Zeichen sein, dass die Usability extrem schlecht ist von der Software und darum immer alle auf die Hilfe Seiten gehen. Und das heißt ja noch lange nicht, dass die Dokumentation gut ist. Also ist ja wirklich wahrscheinlich schwierig, da überhaupt eine Metrik zu finden, oder? Gibt es da irgendwelche Metriken, die man vielleicht verwenden könnte?

Jana Aydinbas (00:18:06 - 00:18:34)

Ja, grundsätzlich muss man gut überlegen, was sinnvoll wäre. Also so E Commerce Metriken können nicht eins zu eins übernommen werden, wo man schaut, wie oft wird die Seite aufgerufen, was für eine Conversion gibt es, gibt es überhaupt Conversion bei Doku und was sagt das alles über mein Produkt aus? Aber Metriken sollten ja auch kein Selbstzweck sein. Also sinnvoll wäre es z.B. im Kontext des Produkts zu schauen, wie viele Support Anfragen können wir beispielsweise abwenden oder zumindest schnell erledigen, indem wir auf die Doku verweisen.

Wolfi Gassler (00:18:34 - 00:18:53)

Es gibt ja auch diese Rückmeldungen oft, die man so sieht auf Dokuseiten, war diese Seite hilfreich oder so. Jetzt gleich Frage an dich, Andy. Jana, du bist gebirged, aber Andi, klickst du da irgendwas an oder schreibst du ja, war hilfreich, war nicht hilfreich oder ignorierst du die Dinge meistens so, wie ich das zumindest mache.

Andy Grunwald (00:18:53 - 00:18:58)

Also nach dieser Podcast Episode werde ich das natürlich immer ausfüllen.

Wolfi Gassler (00:18:58 - 00:19:02)

Du bist jetzt ausweichend. Moment, ich will wissen, was du da in der Vergangenheit gemacht hast.

Andy Grunwald (00:19:02 - 00:19:40)

Ehrlicherweise, ich gehe auf die Support Seite, drück STRG F, suche meinen Begriff, such diesen einen Satz, der mich zur Lösung bringt und lese in der Regel nicht zwei Sätze davor und auch nicht zwei Sätze danach. Dann versuche ich das, dann klappt das. Ich habe es dann nicht verstanden, warum es geklappt hat und dann schließe ich das wieder. Also ich bin in Bezug auf die Profession, ich glaube, der schrecklichste Benutzer. Ich danke allen technischen Redakteurinnen aber, dass diese dasselbe Wording nutzen, wie ich darüber nachdenke, dass ich da meine Lösung finde. Also es ist ja, ich weiß nicht, Jana, macht dich das glücklich, wenn ich schnell meine Lösung finde?

Jana Aydinbas (00:19:41 - 00:20:04)

Ja, wenn man bedenkt, du nutzt den Suchschlitz beispielsweise, gibst da einen Suchbegriff ein, findest ein Ergebnis, ruft es aus, bist dann eine gewisse Zeit auf der Seite und dann verlässt du sie wieder, ohne noch mal einen anderen Begriff zu suchen oder eine andere Seite zu durchwühlen. Also das könnte man ja auch erheben, diesen Klickweg der Informationsbeschaffung. Da musst du ja gar nicht aktiv eine Rückmeldung geben.

Wolfi Gassler (00:20:04 - 00:20:18)

Weißt du zufällig, ob bei euch in der Firma oder bei anderen Firmen sowas in happiness, wie nennt man denn das, diese Happiness Befragungen des Kunden irgendwie auch drinsteckt ist, gibt es eine gute Doku oder so irgendwas in der Richtung?

Jana Aydinbas (00:20:18 - 00:20:19)

Da fällt mir gerade kein Beispiel ein.

Andy Grunwald (00:20:19 - 00:20:21)

Nee, Customer Satisfaction meinst du?

Wolfi Gassler (00:20:22 - 00:20:35)

Ja, irgendwelche Surveys, die es immer wieder mit Kundinnen gibt oder Firmen im BB Bereich. Könnte mir vorstellen, dass vielleicht eine sinnvolle Frage ist, wie gut ist die Doku, aber keine Ahnung, ob das in der Realität eben wirklich dann auch gemacht wird.

Andy Grunwald (00:20:35 - 00:21:06)

Jetzt habe ich aber deine Dokumentationsseite gefunden und ich habe zufällig denselben Begriff gewählt und habe da meine Lösung gefunden. Und dann fand ich die Dokumentation natürlich qualitativ hochwertig. Und jetzt als meine Frage, gibt es einen weltweiten Standard zur Bewertung von qualitativ hoch hochwertig technischen Dokumentation? Also welche Kriterien werden an den Tag gelegt, wenn man sagt, die technische Dokumentation ist eine gute Sache und die leider nicht so ganz.

Jana Aydinbas (00:21:06 - 00:21:54)

Es gibt Daumenregeln, mit denen kann man arbeiten. Da gibt es so ein paar Blogbeiträge, die findet man unter Five Seas oder Seven Seas und da wird dann aufgelistet, dass Dokumentation z.B. correct, clear, concise, consistent und complete sein sollte. Manchmal gibt es dann noch irgendwie cohesive, communicative, sowas in der Art. Aber das sind eher so Kategorien, wann ist es denn clear, wann ist es verständlich? Das muss ja jedes Unternehmen für sich selber festlegen. Und wenn man aber formaler das möchte, dann gibt es eine Norm von IEEE i zur Erstellung von Nutzungsinformationen und da steht was ähnliches drin. Also sollte vollständig sein, korrekt, prägnant und solche Dinge.

Andy Grunwald (00:21:54 - 00:22:02)

Mich würde auch nicht wundern, wenn der deutsche Staat auch irgendein Gesetz dafür hat. Also schreibt man Dokumentation in Deutschland oder.

Wolfi Gassler (00:22:03 - 00:22:19)

Ich tue mir immer extrem schwer mit diesen fünf, was sind es in dem Fall, Cs hattest du gesagt, oder? Fünf Cs oder sieben Cs. Bei uns bei der Feuerwehr gibt es so eine A c e Regel, die sich kein Mensch irgendwie merken kann. Es wäre wahrscheinlich auch irgendwie eine deutsche Erfindung.

Andy Grunwald (00:22:20 - 00:22:26)

Wofür steht denn dieses AEE C? Weißt du das? Sorry, aber das müsste, wenn du es einmal gehört hast, das kannst du doch gar nicht mehr vergessen, oder?

Wolfi Gassler (00:22:26 - 00:22:57)

Ich vergiss es immer jedes Mal. Und ich bin mir fast sicher, dass das niemand bei der Feuerwehr weiß. Ich habe es zufällig jetzt gerade gegoogelt, darum weiß ich es. Also ich kann es dir gerne vorlesen von Atem, Gift, Angstreaktion, Ausbreitung der Gefahr und so weiter. Aber ich will da gar nicht mehr langweilen. Mir geht es eigentlich darum, beachtest du das dann, Jana, in deinem täglichen Writing in dem Sinne? Hast du das im Hinterkopf, dass du die Cs wirklich in irgendeiner Form durchgehst? Oder ist das mehr sowas, was dann in irgendeinem ISO Standard steht und man hat es eher so im als im Bauch und hat es im Gefühl?

Jana Aydinbas (00:22:57 - 00:23:11)

Ich habe durchaus Checklisten für größere Doku Aufgaben, wo ich wirklich noch mal abhake, ob das alles erfüllt ist. Ja, aber wenn ich an Release Notes beispielsweise arbeite, dann mache ich keine Checkliste.

Wolfi Gassler (00:23:11 - 00:23:25)

Und ich schätze ja mal, also da kommt ja auch keine Zahl raus am Ende. Da kommt jetzt kein Qualitätslevel 2,4 oder so raus, sondern auch nur genau auf einem sehr high level level, wo man eben sich da bewegt.

Jana Aydinbas (00:23:25 - 00:23:38)

Ja, das sind Kategorien, über die sollte man sich Gedanken machen. Und als Technical Writerin arbeitet man in der Regel mit einem Style Guide. Da schlüsselt man das alles noch mal auf, was denn eigentlich die Zielgruppe ist, an wen wir uns richten mit der Doku.

Wolfi Gassler (00:23:38 - 00:23:44)

Zielgruppe ist schon ein sehr gutes Thema. Kennst du deine Zielgruppe immer? Weil die kann ja auch extrem breit sein, stelle ich mir vor.

Jana Aydinbas (00:23:44 - 00:23:57)

Ja, es gibt auch nicht nur die eine meistens, sondern für entweder ein oder dasselbe Informationsprodukt mehrere. Oder man erstellt als Technical Writerin mehrere Informations für mehrere Zielgruppen.

Wolfi Gassler (00:23:57 - 00:24:02)

Das heißt aber, du hast die Zielgruppe immer im Hinterkopf oder musst sie eigentlich im Hinterkopf haben, wenn du in irgendeiner Form schreibst.

Jana Aydinbas (00:24:02 - 00:24:03)

Ja genau.

Wolfi Gassler (00:24:03 - 00:24:14)

Jetzt ist es immer sehr, sehr schwierig, der Andi liebt ja dieses explain me like I'm five, wenn man für ganz die junge Generation etwas erklärt.

Andy Grunwald (00:24:16 - 00:24:19)

Ja, kann man so beschreiben oder halt.

Wolfi Gassler (00:24:19 - 00:24:22)

Ja, was hast du jetzt gegen meine Beschreibung?

Andy Grunwald (00:24:23 - 00:24:26)

Fünfjährige sind Kinder für die ganz junge Generation.

Wolfi Gassler (00:24:27 - 00:25:05)

Ja heutzutage, da gibt es schon irgendwelche Pianistenstars mit fünf, also das ist ja schon eine andere Welt. Aber hast du dann immer ein gewisses Vokabular im Kopf oder die Zielgruppe, wie die spricht, wie die denkt? Also das sind ja teilweise auch sehr spezifische Domänen wahrscheinlich, wo man extremes Domänenwissen sich aufbauen muss, irgendwie ein Vokabular. Jeder spricht anders, also in der technischen Welt ist es ja schon extrem anders, aber ich stelle mir vor, wenn man da jetzt in, keine Ahnung, medizinische Welt geht, wirtschaftliche Welt, Versicherungen, die haben ja alle irgendwie ihre eigenen Wörter und Terminologien.

Jana Aydinbas (00:25:05 - 00:25:16)

Das muss man alles bedenken. Es gibt einerseits Fachterminologie aus dem Fachbereich, dann gibt es ja noch unternehmensspezifische Terminologie, wie hat ein Feature wie einen bestimmten eigenen Namen, der verwendet wird.

Wolfi Gassler (00:25:16 - 00:25:34)

Und wenn du dann diese Wörter verwendest, der Andi hat es ja schon erwähnt, der Andi hat vielleicht was ganz anderes im Kopf als Wort. Also verwendest du dann möglichst viele verschiedene Wörter, Synonyme, um das irgendwie durchsuchbar zu machen oder ist der best practice, dass man immer dieselben Wörter verwendet? Also wie geht man denn da vor?

Jana Aydinbas (00:25:34 - 00:25:55)

Ja, man macht es möglichst konsistent, wenn man eine Terminologie festlegt, dann legt man meistens eine Hauptbenennung fest und legt sogar verbotene Benennungen fest, die dann nicht verwendet werden sollen, weil man möchte das möglichst konsistent Dokumentation erstellen, damit die beispielsweise auch konsistent übersetzt werden kann.

Andy Grunwald (00:25:55 - 00:26:18)

Aber kann man da nicht eigentlich mit Suchmaschinenoptimierung irgendwie Synonyme irgendwie so festlegen oder bin ich dann wirklich auf Google angewiesen, dass Google dann die Synonyme kennt? Weil machen wir uns mal nichts vor, vielleicht kenne ich den Begriff, den ihr verwendet halt nur unter einem anderen, unter einem anderen Wort oder ähnliches. Also dann bin ich ja schon auf externe Suchmaschinen drauf angewiesen, oder um, ich sag mal, schnell da navigieren zu können.

Jana Aydinbas (00:26:18 - 00:26:29)

Ja, wenn es eine frei zugängliche Onlinehilfe wäre, dann müsste man sich um SEO noch Gedanken machen, aber wir im speziellen Fall liefern unser Online Hilfe ja aus für eine lokale Nutzung.

Wolfi Gassler (00:26:29 - 00:26:34)

Machst du eigentlich Mehrsprachigkeit auch oder bist du nur auf eine Sprache fixiert?

Jana Aydinbas (00:26:34 - 00:26:40)

Aktuell dokumentiere ich nur auf Deutsch in früheren Projekten habe ich aber auch schon auf Englisch Dokumentation erstellt.

Wolfi Gassler (00:26:40 - 00:26:44)

Und gibt es diese Dokumentation dann in anderen Sprachen auch? Also wird die dann irgendwie übersetzt?

Jana Aydinbas (00:26:45 - 00:26:50)

Ja, bei uns wird übersetzt, genau. Das geht raus an eine Übersetzungsagentur und.

Wolfi Gassler (00:26:50 - 00:26:58)

Die muss dann aber wieder diese ganzen Spezialbegriffe und so weiter übersetzen. Macht die das selbst oder sind die dann auch Domainspezialisten oder wie läuft das ab?

Jana Aydinbas (00:26:58 - 00:27:02)

Die bekommen von uns unsere Terminologie und verwenden die auch.

Wolfi Gassler (00:27:02 - 00:27:08)

Und ihr macht dann die eigentliche Übersetzung von den Spezialbegriffen nach Französisch oder sonst wohin?

Jana Aydinbas (00:27:08 - 00:27:20)

Nein, den Übersetzungsteil macht die Agentur auch. Also wir geben eine deutsche und teilweise auch englische Terminologie raus, aber es wird auch in französisch und italienisch übersetzt.

Wolfi Gassler (00:27:21 - 00:27:30)

Also ihr definiert, was die Spezialwörter überhaupt sind und die Agentur kümmert sich dann speziell um diese Fachbegriffe, was das in der jeweiligen Sprache dann bedeutet.

Jana Aydinbas (00:27:30 - 00:27:44)

Ja, und das ist aber eine große Herausforderung, weil die Fachbegriffe teilweise spezifisch für den deutschen Markt sind. Wie macht man das dann im italienischen beispielsweise? Also das ist wirklich nicht ohne das Thema Übersetzung.

Wolfi Gassler (00:27:44 - 00:27:55)

Wie läuft es dann ab mit der Oberfläche? Weil wenn du jetzt irgendwie beschreibst Menüpunkte oder sowas, dann müssten das ja die Menüpunkte dann in der jeweiligen italienischen Version sein.

Jana Aydinbas (00:27:55 - 00:28:12)

Ja, unsere GUI wird auch übersetzt und da ich die Ressourcen von den Softwareentwicklern verwende in meiner Doku, ist das alles konsistent und einheitlich. Und wenn das aus der Übersetzung zurückkommt, wird es sowohl in der Doku als auch in der GUI verwendet.

Wolfi Gassler (00:28:12 - 00:28:27)

Das heißt, wenn du jetzt Datei speichern quasi verwenden würdest, dann greifst du da auf irgendwie eine zentrale Datenbank zu, wo du sagst, ich will dieses Element haben und wenn das dann von einer Programmiererin geändert wird, dann wird das automatisch in der Dokumentation mitgeändert.

Jana Aydinbas (00:28:27 - 00:28:28)

Genau, ja.

Wolfi Gassler (00:28:28 - 00:28:39)

Okay, cool. Das heißt aber, euer Dokumentationssystem ist dann auch relativ komplex und irgendwie verknüpft mit eben mit zentralen Ressourcen von der Entwicklerseite?

Jana Aydinbas (00:28:39 - 00:28:50)

Ja, wir haben ein proprietäres CCMS, ein Component Content Management System und das hat Schnittstellen, das wird synchronisiert mit den anderen Systemen, die wir so haben.

Andy Grunwald (00:28:51 - 00:29:45)

Vor ein paar Jahren gab es mal irgendwie, also nur als Anekdote so, vor ein paar Jahren gab es mal irgendwie so den Hype, dass irgendjemand mal ein Programmierbuch geschrieben hat und in late oder ähnliches und dort waren Quellcode Beispiele und als dann das Buch kompiliert wurde oder ich sag mal erstellt wurde, als ein PDF rausgerendert wurde, dann wurden diese Quellcode Beispiele auch getestet auf Syntax und so weiter und so fort. Und da wurde ganz groß wurde irgendwo im Internet total gefeiert, Hacker News oder sowas. Und jetzt kommst du daher und sagst, ja, das ist völlig Standard hier, weil im Endeffekt macht ihr ja eigentlich genau das gleiche. Ihr macht ja auch so halbe Magie. Ja, also ich meine, ihr habt ja dann im CMS, stelle ich mir zuvor irgendwelche Source Code Files und die nehmen sich dann die Begriffe daraus. Schon geil. Also ich frage mich gerade, ob die ganzen Leute im Open Source Bereich nicht irgendwie im Dokumentationsschreiben noch irgendwie im Steinzeitalter sind.

Jana Aydinbas (00:29:45 - 00:29:52)

In der Right the Docs Community sind mir auch schon Beispiele begegnet, wo Quellcode beispielsweise zeilenweise in die Doku referenziert wird.

Wolfi Gassler (00:29:53 - 00:30:00)

Wie sieht es dann mit Screenshots aus? Oder weil die sind ja dann wirklich hart gecodet, wenn man so will.

Jana Aydinbas (00:30:00 - 00:30:02)

Ja, die vermeiden wir nach Möglichkeit.

Wolfi Gassler (00:30:03 - 00:30:05)

Also die gehen noch nicht automatisch.

Jana Aydinbas (00:30:06 - 00:30:20)

Doch, da habe ich auch mal einen Talk zu gesehen, wie man die automatisch generieren lässt. Da gibt es ein Tool zum testen, Selenium. Da sind die Screenshots quasi ein Abfallprodukt und die könnte man auch in der Doku verwenden.

Wolfi Gassler (00:30:20 - 00:30:40)

Das stimmt. Das heißt, ihr braucht natürlich immer einen Test dazu, aber wenn ich einen Test hätte, könnt ihr ihn screenshotten und dann ging das natürlich. Wobei das in den verschiedenen Sprachen dann auch schon wieder die Frage ist, weil da müsst ihr auch womöglich irgendwelche Eingaben in verschiedenen Sprachen machen. Also hat schon recht langen Rattenschwanz, aber ziemlich komplexes Problem, mehr bei komplexer Software, die multilingual ist.

Andy Grunwald (00:30:40 - 00:31:00)

Aber eigentlich ein supergeiler Use Case von Selenium, wo ich gerade drüber nachdenke, hatte ich so auch noch nicht auf dem Zettel. Jetzt wird die Frage noch nicht gestellt und ich muss sie jetzt stellen, die Stereotypen Frage. Wie sieht es denn mit AI aus, mit künstlicher Intelligenz, mit ChatGPT? Ist jetzt dein Job in Gefahr oder wie siehst du das?

Jana Aydinbas (00:31:00 - 00:31:37)

Aktuell würde ich sagen, noch nicht. Also mit den allgemein verfügbaren Tools arbeite ich schon so ein bisschen. Damit kann man ganz gut die Situation nachstellen. Man ist im Büro, man guckt vom Schreibtisch auf zur Kollegin links oder rechts und stellt mal eine. Wie kann ich es noch formulieren? Fällt dir ein anderes Wort dafür ein? So dieses Brainstorming funktioniert ganz gut damit. Aber ansonsten brauche ich für die Dokumentationserstellung eben Domänen und unternehmensspezifisches Wissen. Und eine Qualitätsanforderung für die Doku ist, dass sie korrekt sein muss. Und da ist mir das mit den Halluzinationen noch zu gefährlich.

Wolfi Gassler (00:31:37 - 00:32:16)

Ich habe kürzlich gehört von einem Produkt, von so einem Ticketing System, die lassen automatisch bei jedem Ticket, was ja teilweise sehr lang sein kann, wenn es irgendwo ein Ping Pong mit dem Kunden ist und so weiter und irgendwelche Supportanfragen, die lassen ganz oben automatisiert eine Zusammenfassung erstellen von GPT oder von irgendeinem LLM, um einfach einen schnellen Überblick über das Ticket zu bekommen. Also ihr könnt mir vorstellen, sowas könnte vielleicht auch hilfreich sein, vor allem, wenn du jetzt sagst, das ist immer so eine extreme Recherche durch diese ganzen Tickets und so weiter. Also hast du da gibt es da bei Jira schon was? Hast du da Anknüpfungspunkte oder habe ich jetzt irgendwie eine Geschäftsidee gerade kreiert?

Jana Aydinbas (00:32:17 - 00:32:24)

Wie Andi vorhin erwähnt hat, das Jira Ticket muss dann schon sehr gut gepflegt sein, dass man da automatisch Doku draus generieren kann.

Andy Grunwald (00:32:24 - 00:32:26)

Investigativer Journalismus.

Wolfi Gassler (00:32:26 - 00:32:48)

Ich meine, es kann nicht automatisch Doku generieren, aber dass dir das Leben bei der Recherche vereinfacht wird, dass du Zusammenfassungen bekommst, dass du nicht mehr alle Einzelpunkte durchlesen musst, dass du ganz oben z.B. immer hast, okay, der aktuelle Status von dem Decked ist so und so, es wurden diese fünf Hauptpunkte gemacht, so eine high level Zusammenfassung von einem komplexen, von einer komplexen User Story z.b. das hört.

Jana Aydinbas (00:32:48 - 00:32:49)

Sich wiederum hilfreich an. Ja.

Wolfi Gassler (00:32:49 - 00:32:54)

Das heißt, ihr hattet aber, wenn ihr das richtig verstehe, in der freien Wildbahn noch keinen Kontakt damit.

Andy Grunwald (00:32:54 - 00:32:59)

Ja, vielleicht unfreiwillig so ein bisschen. Also wir benutzen als Datenbank bei dir.

Wolfi Gassler (00:32:59 - 00:33:01)

Ist alles mit ChatGPT unfreiwillig.

Andy Grunwald (00:33:01 - 00:33:52)

Na, das stimmt nicht, ich bessere mich. Aber als Datenbankhäuser haben wir natürlich auch so eine Art Support wie AWS oder ähnliches und da haben wir ein externes Ticketsystem, was wir einkaufen als Software as a Service und da haben wir mal hier und da mal so AI Summaries ausprobiert. Ich muss zugeben, ich war bisher noch nicht überzeugt. Vielleicht lag es irgendwie an den an den Detailspezifika, wenn es um Datenbankkonfiguration geht und das vielleicht nicht jedes Setting da in seiner Wort Datenbank drin war oder sowas. Aber ab und zu kam da schon relativ großer Murks raus, zumindestens wenn du in Kundenkommunikation bist, dann sind manche Details sehr wichtig und da wurden ziemlich viele Details raus ausgelassen. Also bisher war ich noch nicht happy. Auf der anderen Seite gebe ich aber auch zu, das war nicht gerade erst gestern. Also wenn ihr da jetzt GPT, wo sind wir? 11, weiß ich nicht, wo sind wir? Vier Punkt irgendwas, vielleicht könnt ihr was besseres.

Jana Aydinbas (00:33:52 - 00:34:02)

Ich muss mich anschließen, wir verwenden Confluence Cloud bei der Arbeit und da gibt es eine AI, die fasst z.B. conference Seiten zusammen und die Qualität ist so lala, würde ich sagen.

Wolfi Gassler (00:34:02 - 00:34:23)

Ich meine, man muss natürlich dazu sagen, dass Zusammenfassungen dafür da sind, schnell einen groben Überblick zu bekommen. Und per Definition können in einer Zusammenfassung ja nie alle Details drinnen sein. Also wenn da Andi da irgendwelche Datenbank Dinge erwartet, die irgendwie in Konfigs drinstehen und so, dann wäre es ja keine Zusammenfassung. Aber wenn die Zusammenfassung an sich schon misleading ist, ist es natürlich ein Problem.

Andy Grunwald (00:34:23 - 00:34:32)

Ja, vielleicht ist es dann auch die Frage, okay, ist eine Zusammenfassung in dem Kontext, in dem jetzt Jana und ich das erwarten, sinnvoll? Weiß ich jetzt dann auch nicht.

Wolfi Gassler (00:34:32 - 00:34:39)

Wäre schon was für die. Andy, du als Manager, du könntest einfach schauen, ist es aber, dir ist der Status der wichtigste erledigt oder noch offen, oder?

Andy Grunwald (00:34:40 - 00:34:51)

Ja, und sehe das mal so, immer wenn ich in ein Customer Support Ticket reingeholt werde, dann geht es meist um Probleme. Dann läuft irgendwas nicht gut, dann muss ich da, weiß ich nicht, oder ich muss gerade meinen Kopf da. Ich weiß es nicht.

Jana Aydinbas (00:34:51 - 00:35:23)

Ich habe aber auch schon sinnvolle Nutzungsszenarien gesehen für Ai. Da gab es noch einen Vortrag, da wurden in einer Dokumentationsveröffentlichungspipeline z.B. dateinamen erstellt. Aufgrund des Bildinhaltes wurden Dateinamen erstellt oder Alttexte wurden automatisch erstellt. Das sind so Fleißarbeiten, die man gerne übersieht. Das sind Accessibility Themen, das schiebt man ja meistens sowieso thematisch sonst wo an den Rand. Und sowas kann automatisch generiert werden und einen Mehrwert schaffen.

Andy Grunwald (00:35:23 - 00:35:44)

Aber lass uns mal über die richtigen Probleme von Entwicklerinnen und Entwicklern reden. Und zwar, leider muss oft Dokumentation geschrieben werden. Und ein weit verbreiteter Mythos ist, wieso soll ich denn Dokumentation schreiben? Weil wenn sie denn geschrieben ist, ist sie ja dann schon out of date, dann lohnt sich es ja gar nicht, die im ersten Schritt überhaupt zu schreiben. Wie stehst du dazu, zu dieser Aussage?

Jana Aydinbas (00:35:44 - 00:36:02)

Das ist ein Fakt. Es gab mal einen Write the Dogs Vortrag, der hieß Always complete, never finish. Und da ging es darum, dass Dokumentation wirklich nie ganz abgeschlossen ist und dass man vor einem Berg an Arbeit steht. Aber wenn man sich da schrittweise ran wagt, kann es trotzdem ein lohnenswerter Aufwand sein.

Andy Grunwald (00:36:02 - 00:36:08)

Aber ist out of date Dokumentation nicht eigentlich schlimmer als gar keine Dokumentation?

Jana Aydinbas (00:36:08 - 00:36:23)

Kommt drauf an. Wenn sie grob irreführend ist und zu Personen oder Sachschäden führt, ja. Aber wenn es eine Funktion umbenannt wurde und noch an derselben Stelle zu finden ist, Muscle Memory immer noch, greift dann dein.

Andy Grunwald (00:36:25 - 00:36:31)

Der zweite Mythos, der mir auch immer einfällt, ist, niemand liest Dokumentation. Offen gesprochen, ich bin ja auch eine Vorlaufperson und wenn neben mir, der Wolfgang.

Wolfi Gassler (00:36:31 - 00:36:34)

Sitzt eh neben dir.

Andy Grunwald (00:36:34 - 00:36:47)

Ja, dann frage ich auch lieber den Wolfgang, anstatt mich durch Dokumentationen zu wühlen und die Lösung zu finden. Also ist die Frage, ist das wirklich so, dass niemand Dokumentation liest?

Jana Aydinbas (00:36:47 - 00:36:49)

Ja, das wollte ich euch fragen. Ist das so?

Andy Grunwald (00:36:50 - 00:37:04)

Ich weiß nicht, heutzutage ChatGPT ist glaube ich auch. Kann ich lieber die Frage formulieren. Auf der anderen Seite, ChatGPT holt die Antwort aus der Dokumentation. Vielleicht ist sie heutzutage mit ChatGPT deutlich relevanter, keine Ahnung.

Wolfi Gassler (00:37:04 - 00:37:51)

Also ich habe mit meinem initialen Beispiel eigentlich schon gezeigt, dass man sehr wohl Dokumentation liest. Also ich glaube, wenn man da an auch gute Dokumentationsbeispiele, APIs denkt, gerade als Entwickler in braucht man eigentlich tagtäglich und was würde man ohne der sinnvollen Dokumentation machen? Und was glaube ich auch sehr wichtig ist, dass man dadurch extrem performant sein kann und man spart sich da extrem viel Zeit, weil wenn du es schaffst, durch eine Dokumentation schnell zu dem Punkt zu kommen, wie du etwas umsetzen willst, egal ob es jetzt Code ist, was programmieren, eine API ansprechen, dann sparst du dir extrem viel Zeit, wenn du da sonst irgendwie 2 Stunden Stack Overflow durchgehen müsstest oder hoffen, dass es vielleicht Copilot weiß. Aber bei APIs ist es auch immer schwierig und wahrscheinlich gibt es da auch ziemlich viel Literatur, die das beweist.

Jana Aydinbas (00:37:51 - 00:38:41)

Ich würde sagen, an niemand liest die Dokumentation ist schon was dran, weil ja niemand quasi linear die Dokumentation von Anfang bis Ende liest. Also ich mache das schon, wenn ich mir ein neues Produkt kaufe, dass ich mir die Anleitung durchlese, um zu wissen, was es kann. Aber bei Softwaredokumentation tendenziell eher nicht so. Aber man kommt ja auf die Doku zurück, wenn man Hilfe braucht. Also man nutzt sie als Referenz. Es gibt auch tatsächlich Belege, dass Dokumentation gelesen wird und hilfreich ist. Es gab Google State of DevOps von 2023 herausgefunden, dass die Team Produktivität steigt um 25 %, wenn das Team eine gute Dokumentation hat. Und in Githubs octoberse Report wurde auch festgestellt, dass sowohl in Open Source Projekten als auch in Unternehmen Entwickler sogar bis zu 50 % Produktivitätssteigerung haben mit guter Dokumentation.

Andy Grunwald (00:38:42 - 00:39:02)

Aber wenn das doch schon so ein großer Enabler ist und besonders in der Karriere einer Softwareentwicklerin ist es ja so, dass man um so einen größeren Impact man hat, man höher in der Hierarchie ist und so weiter und so fort und anderes Gehalt. Warum ist dann Dokumentation schreiben nicht attraktiv? Warum sagen Leute ich hasse es Dokumentation zu schreiben?

Wolfi Gassler (00:39:02 - 00:39:10)

Das müsstest du dir selber beantworten, Andy. Du bist noch hin und wieder zumindestens Entwickler neben deiner Engineering Manager laufbar ja.

Andy Grunwald (00:39:10 - 00:39:14)

Ich glaube, mir fehlen einfach die Daten, ob meine Dokumentation gelesen wird.

Wolfi Gassler (00:39:15 - 00:39:17)

Die hast du jetzt gerade bekommen, das ist keine Ausrede mehr.

Andy Grunwald (00:39:18 - 00:39:38)

Ne, ne, in Bezug auf, ich sage nicht, dass Dokumentation jetzt nicht super vorteilhaft ist. Ich sage nur, soll ich jetzt die Zeit investieren, diese Dokumentation zu schreiben? Wie viele Leute lesen das denn? Also ich meine, meine Software ist ja jetzt nicht so wichtig wie jetzt die Dokumentation an der Waschmaschine. Die wird glaube ich zehnmal mehr gelesen als meine Software jetzt z.b. vielleicht wird.

Wolfi Gassler (00:39:38 - 00:39:41)

Deine Software nur nicht verwendet, weil es keine sinnvolle Dokumentation gibt.

Andy Grunwald (00:39:41 - 00:39:55)

Ja, das eine kann dazu führen, das ist korrekt. Aber Jana, was denkst du, warum Software schreiben generell Software schreiben? Software schreiben ist auch nicht attraktiv, gebe ich auch zu. Aber Dokumentation Schreiben wird zumindest als nicht attraktiv angesehen.

Jana Aydinbas (00:39:55 - 00:40:26)

Zum einen wird der Wert von Dokumentation nicht erkannt, aber liest ja eh keiner. Dann ist es kein einmaliger Aufwand, sondern es ist wirklich aufwendig von der Konzeption zur Umsetzung. Und das ganze muss laufend aktuell gehalten werden und kann frustrierend sein, wenn man dann die Erwartung hat, jeder kann schreiben und dann gelingt es einem doch nicht so gut. Und vielleicht ist man auch nicht gut darin, weil man es nicht gelernt hat. Also jeder kann schreiben lernen, aber das muss man halt auch erstmal, damit es Spaß machen kann.

Wolfi Gassler (00:40:26 - 00:40:40)

Hast du gute Dokumentation auch von der Entwicklerseite mal gesehen oder würdest du sagen, das ist automatisch, wenn das Entwicklerinnen machen, ist es automatisch irgendwie möglichst kurz, oder? Oder gibt es da auch Positivbeispiele?

Jana Aydinbas (00:40:40 - 00:41:05)

Ja klar. Also bei Write the dogs gibt es den Begriff Documentarian. Das meint, dass man, egal welche Berufsbezeichnung man hat, wenn man sich für Dokumentation interessiert, dann ist man Documentarian und das kann Entwickler in sein oder Technical Writer in. Und insbesondere bei Developer Dokumentation kommt es ja vor, dass die von Entwicklerinnen erstellt wird und die muss nicht per se schlecht sein. Nein.

Wolfi Gassler (00:41:05 - 00:41:08)

Schreibst du eigentlich API Dokumentation auch?

Jana Aydinbas (00:41:08 - 00:41:11)

Jetzt aktuell schreibe ich mit, ja.

Wolfi Gassler (00:41:11 - 00:41:14)

Aber das ist dann immer gemeinsam mit dem Team.

Jana Aydinbas (00:41:14 - 00:41:14)

Genau, ja.

Wolfi Gassler (00:41:14 - 00:41:28)

Jetzt ist natürlich eine interessante Frage, wenn du sagst, okay, Developer innen, die können ja auch Dokumentation schreiben und vielleicht kann man die auch motivieren dazu. Dann wäre jetzt schon die Frage, braucht es überhaupt diesen Beruf Technical Writer?

Andy Grunwald (00:41:28 - 00:41:32)

Du bist eine richtig fiese MÖP, weiß er das? Eine richtig fiese MÖP.

Jana Aydinbas (00:41:32 - 00:42:00)

Ich würde schon sagen, dass es Technikwriterinnen braucht und wenn nur als Multiplikatoren. Manche Unternehmen können sich ja gar nicht für jedes Team Technical Writer innen leisten und da sind die Technikwriterinnen dafür zuständig, z.b. ein Style Guide zu entwerfen oder Templates zu entwerfen, die den Entwicklerinnen das Leben leichter machen. Also zumindest in dieser Rolle sollte schon jemand vorhanden sein. Ich finde spezialisierte Rollen sinnvoll, weil jeder unterschiedliche Kompetenzen mitbringt.

Andy Grunwald (00:42:00 - 00:42:04)

Ich würde den Wolfgang einfach mit folgendem Kommentar auseinandernehmen. Wolfgang.

Wolfi Gassler (00:42:04 - 00:42:06)

Ah, jetzt bin ich gespannt. Ja, bitte.

Andy Grunwald (00:42:06 - 00:42:11)

Wann hast du mal ein gutes Wiki oder ein gutes Konfluent gesehen, was gut strukturiert war?

Wolfi Gassler (00:42:11 - 00:42:14)

Ja, aber das liegt nur an der Software, logisch.

Andy Grunwald (00:42:14 - 00:42:17)

Das liegt nicht daran, wie die Informationen darin organisiert sind. Richtig.

Wolfi Gassler (00:42:18 - 00:42:19)

Es liegt nur an der Software, logisch.

Andy Grunwald (00:42:19 - 00:42:21)

Ja gut, haben wir schon.

Wolfi Gassler (00:42:21 - 00:42:32)

Außerdem für mich als Entwickler, der Code ist doch die Dokumentation. Da kann dann jeder alles nachschauen und findet alles darin. Das Argument höre ich tagtäglich.

Andy Grunwald (00:42:32 - 00:42:33)

Hörst du sowas auch, Jana?

Jana Aydinbas (00:42:33 - 00:42:44)

Habe ich auch schon gehört, ja. Und wenn der Code kommentiert ist, dann kann das schon sein, ja. Aber wenn nicht, dann viel Erfolg, weil der Code gibt ja eher das was wieder und nicht das wieso.

Andy Grunwald (00:42:44 - 00:42:52)

Ich glaube, der Wolfgang hat noch nie mit einer Software gearbeitet, die irgendwie 1 Million Zeilen Code hat oder ähnliches, weil da hilft auch die beste Code Dokumentation einfach mal gar nichts.

Wolfi Gassler (00:42:55 - 00:43:02)

Ich glaube, du brauchst keine Million Zeilen, dass das ein Chaos wird. Das geht schon viel, viel früher los. Definitiv, ja.

Jana Aydinbas (00:43:02 - 00:43:05)

Wisst ihr schon, was ihr. Wisst ihr noch, was ihr letzte Woche gemacht habt und wieso?

Wolfi Gassler (00:43:05 - 00:43:11)

Da hast du Andis Lieblingsfrage. Er fragt mir immer, was habe ich gestern zu Mittag gegessen oder so. Und ich kann schon immer nicht beantworten.

Andy Grunwald (00:43:11 - 00:43:57)

Ich erzähle zwar immer gerne lange Stories in Quellcode und schreibt dann auch wirklich so 1020 dreiig Zeilen, meist mit dem warum wir diesen Hack jetzt hier implementieren. Aber ich weiß nicht, ob ich es jetzt, also jetzt, wo ich darüber nachdenke, weiß ich nicht, ob ich es zur Dokumentation mache oder zur Rechtfertigung, dass dieser Hack genauso bleibt und ich mir nicht mehr Mühe gegeben habe, das ordentlich zu implementieren. Aber wie dem auch sei, ich glaube, beides führt zum selben Ergebnis. Jetzt hattest du gesagt, dass du in zwei Software Teams unterwegs bist und motivierst du dann ab und zu auch mal die Entwickler, dass die die Dokumentation schreiben? Sagst du nicht hey, in dem anderen Team, da ist gerade so viel zu tun, könnt ihr nicht mal die Dokumentation schreiben?

Jana Aydinbas (00:43:57 - 00:44:16)

Ja, das kommt vor, dass ich die Entwickler sowas bitte. Ich bin eben Teil von zwei Scrum Teams und wir machen auch retro und da reflektieren wir schon darüber, was wir gemacht haben, den Sprint über, was gut funktioniert hat und was nicht. Und da gab es neulich eine Situation, wo ich darum gebeten habe, dass die Entwickler mir mehr Informationen zukommen lassen über bestimmte Themen. Ja.

Wolfi Gassler (00:44:16 - 00:44:40)

Aber jetzt haben wir die ganze Zeit eigentlich so über Software gesprochen und Softwaredokumentation. Aber wenn man jetzt so an den Alltag denkt, dann hat man ja ganz oft mit mit Hardware Dokumentation, ganz klassischen Manuals, wenn ich mal so sie beiläufig nennen darf, zu tun. Fällt es dann auch in dieses Jobprofil vom Technical Writer und Writerin oder ist es dann was anderes?

Jana Aydinbas (00:44:40 - 00:44:53)

Ja genau. Technical Writerinnen sind sowohl für Software als auch Hardware Dokumentation zuständig und ich habe bei meinem vorherigen Arbeitgeber auch hardware Dokumentationsprojekte gehabt und die haben durchaus andere Anforderungen.

Andy Grunwald (00:44:53 - 00:44:58)

Das bedeutet, wenn ich jetzt hier ein Raspberry Pi auspacke, dann könnte da deine Dokumentation drin sein?

Jana Aydinbas (00:45:00 - 00:45:10)

Nein, für Raspberry Pi habe ich keine Doku geschrieben, aber für z.B. haushaltsgeräte oder Automatisierungstechnik oder Medizintechnik oder was sind denn.

Andy Grunwald (00:45:10 - 00:45:13)

Die essentiellen Unterschiede zwischen Hard und Software Dokumentation?

Jana Aydinbas (00:45:13 - 00:45:51)

Für die Hardware Dokumentation gibt es z.B. die Maschinenverordnung, das ist eine EU Richtlinie, die vorschreibt, dass für den europäischen Wirtschaftsraum für Geräte z.b. eine Gefahrenanalyse gemacht werden muss. Es müssen Warnhinweise erstellt werden und es muss eine Doku geben und wie lange die aufbewahrt werden muss und solche Dinge. Und eine Maschine oder ein Gerät hat auch einen bestimmten Zyklus, also einen Lebenszyklus, wie eine Montage, eine Installation und eine Inbetriebnahme. Dann wird das Ganze betrieben und gewartet und repariert und irgendwann wird es außer Betrieb genommen, abgebaut, entsorgt, solche Sachen. Und ich würde sagen, bei Software gibt es oftmals nicht so eine eins zu eins Entsprechung.

Wolfi Gassler (00:45:52 - 00:45:56)

Also wenn ich das richtig sehe, ist der Hardwarebereich auch wesentlich mehr reglementiert dann?

Andy Grunwald (00:45:56 - 00:46:21)

Genau, ja, bei der Gefahrenanalyse, kennt ihr dieses Beispiel aus Amerika oder diesen, was es wohl anscheinend wirklich gab? Da hat sich jemand einen heißen Kaffee bei McDonald's geholt, ist dann aus dem McDonald's raus und sich ins Gesicht geschmissen und hat dann McDonald's verklagt, weil auf der auf der Kaffeetasse dann sehr wahrscheinlich nicht drauf stand Achtung, heiß darf man sich nicht ins Gesicht schütten. Da gab es auch irgendwas mit einem Hamster, der in der Mikrowelle gelandet ist, weil dann auch, weil der Verkäufer Andy.

Wolfi Gassler (00:46:21 - 00:46:23)

Kennt alle Urban Legends, oder?

Andy Grunwald (00:46:23 - 00:47:03)

Dass man diesen Hamster nicht in der Mikrowelle stecken kann. Ja, du hast gesagt Gefahrenanalyse, Warnhinweise, da muss ich irgendwie an sowas denken. Aber jetzt wo du, wo du über den Lebenszyklus an der Maschine gesprochen hast, ich habe mich noch nie bis gerade gefragt, dass das ein System hat. Ich habe am Wochenende meinen Aufsitzrasenmäher repariert und ja, ich habe die Anleitung gemacht und ja, da waren ganz genau die Punkte Montage, Installation, Betriebnahme, Wartung, Reparatur und so weiter und mein Auto VW Golf muss bald zum TÜV. Da habe ich auch in der Anleitung nachgeguckt und habe die gleichen Punkte gefunden. Ich gebe zu, ich habe mich das noch nie gefragt, aber jetzt macht das alles irgendwie total Sinn.

Jana Aydinbas (00:47:03 - 00:47:12)

Ja, da geht es auch um Produkthaftung. Im Produkthaftungsgesetz steht, glaube ich, sinngemäß drin, dass ein Produkt nur vollständig ist mit einer Doku, die Gefahren vermeidet.

Andy Grunwald (00:47:12 - 00:47:16)

Aber heißt das jetzt im Umkehrschluss, dass das jetzt eine Software diese Warnhinweise nicht braucht?

Jana Aydinbas (00:47:16 - 00:47:31)

Kann man gar nicht so sauber trenden, weil wenn es eine Medizintechnik Software ist, die beispielsweise Laborgerät oder so steuert, dann kann das durchaus schon eine Gefahr geben für Mensch und Gegenstand. Und Datenverlust ist natürlich auch immer denkbar.

Andy Grunwald (00:47:31 - 00:47:55)

Warnhinweis, diese Datenbank kann Daten verlieren. Jetzt sprechen wir ja komplett über professionelle Dokumentationen und jetzt möchte ich mal ganz kurz auf den Open Source Bereich zurückkommen. Der Open Source Bereich ist ja in vielen Bereichen ebenfalls sehr professionell unterwegs, aber in manchen Bereichen gibt es dann immer noch so ein bisschen Nachholbedarf. Wie nimmst du denn die Dokumentation im Open Source Bereich wahr im Vergleich jetzt zum professionellen Umfeld?

Jana Aydinbas (00:47:55 - 00:48:41)

Ich habe ehrlich gesagt nicht so viel Erfahrung Open Source, aber in der Reddox Community wird es oft besprochen und da kommt schon mal das Thema vor, dass in Open Source Projekten Dokumentation auch nicht gerne geschrieben wird. Viele Entwicklerinnen arbeiten lieber an neuen Features anstatt zu dokumentieren, weil wir haben ja vorhin schon darüber gesprochen, es ist einfach aufwendig, Dokumentation zu erstellen und zu pflegen. Und deswegen gibt es oftmals sowas wie Referenzen, also Umgebungsvariablen, Listen oder irgendwas, was man halt alphabetisch oder thematisch sortieren kann, in Tabellen gelistet oder so. Da ist der Aufwand gering und das kann auch einen großen Nutzen haben, aber meistens besteht in Wirklichkeit Bedarf an Tutorials und die zu erstellen ist aufwendig.

Wolfi Gassler (00:48:41 - 00:49:28)

Ich habe gerade kürzlich bei ChatGPT auch wieder mal wegen dem kleinen Test eingegeben, wie kann ich beurteilen, ob eine Open Source Library gut ist, ob ein Open Source Projekt gut ist und ob ich das im professionellen Einsatz geben soll. Und ein wichtiger Punkt, der da rausgesprungen ist, ist Dokumentation. Ist die Dokumentation gut? Wie umfangreich ist die Dokumentation? Gibt es eine Community, wo Fragen gestellt werden und so weiter? Also sogar da ist es eigentlich schon ein Standard Element und das würde ich auch unterschreiben. Wenn ich bewerten will will, ob ich Open source einsetze, dann schauen wir natürlich auch die Dokumentation an, ob die gut ist. Und meiner Meinung nach, wenn du dir gute Software anschaust, die auch weit verbreitet ist, irgendein Engine x oder so, der hat eine sehr gute Dokumentation, würde ich mal sagen.

Andy Grunwald (00:49:28 - 00:50:02)

Du hast jetzt aber auch den den Bedarf an Tutorials angesprochen. Das bringt mich zum Nachdenken, weil das tolle an Open Source ist ja, dass du im Internet auch diese ganzen Webblocks hast und ich ja, ich schreibe keine react Dokumentation z.b. aber theoretisch kann ich ja in meinem Blog einen React Tutorial schreiben und das tun ja auch sehr viele. Das ist natürlich schon ein essentieller Vorteil von Open Source gegenüber, ich sag mal proprietärer Dokumentation von der Waschmaschine. Da schreibt ja jetzt keiner ein Waschmaschinen Tutorial oder sowas, oder? Wie stehst du dazu?

Jana Aydinbas (00:50:02 - 00:50:19)

Ja klar, das ist ein großer Vorteil, aber man muss bedenken, funktioniert das für jede Version? Funktioniert das für jedes Setup? Sind alle Voraussetzungen identisch? Ist wirklich alles so beschrieben, dass die Hemmschwelle gering ist, das Tutorial zu starten und zu Ende zu bringen? Da fließt schon einiges mit rein.

Andy Grunwald (00:50:19 - 00:50:28)

Also die Antwort ist, funktioniert das für jede Version? Meine Erfahrung nein, natürlich nicht, denn ich als nicht JavaScript lerne immer irgendwelche Fehler.

Wolfi Gassler (00:50:29 - 00:50:34)

Aber das kannst du ja nicht nur bei Open Source machen, oder? Ich kann ja bei proprietärer Software genauso ein Tutorial machen.

Andy Grunwald (00:50:34 - 00:50:35)

Ja. Machen das viele?

Wolfi Gassler (00:50:35 - 00:50:37)

Wahrscheinlich weniger. Ist eine gute Frage eigentlich.

Andy Grunwald (00:50:37 - 00:50:54)

Also ich meine, es gibt Wettbewerbe, wie z.B. es gibt ja auch Wettbewerbe, wie schnell kann man die Kette einer Kettensäge wechseln? So ist das ein Tutorial? Ja, wenn man das in Slow Motion spielt, bestimmt. Ist eine Kettensäge proprietär? Ja, würde ich auch sagen. Also ich glaube, es kommt immer auf die Hardware an, oder?

Wolfi Gassler (00:50:54 - 00:51:07)

Aber es ist auch keine komplexe Software in der Motorsäge. Noch. Noch nicht. Kommt sicher auch noch. Aber Jan, jetzt hast du schon Ride the Docs extrem oft erwähnt. Kannst du mal erklären, was es eigentlich ist?

Jana Aydinbas (00:51:07 - 00:51:38)

Also Write the dogs ist eine für alle offene Community, für Documentarians, wie vorhin schon und die ist echt wunderbar hilfreich. Zum einen gibt es eine super informative Webseite, es werden Konferenzen und Meetups veranstaltet und alle Videos der Konferenzen sind kostenlos verfügbar. Es gibt einen Newsletter, in dem Slack Diskussionen zusammengefasst werden und es gibt eben für die Community einen Slack mit ganz vielen verschiedenen thematischen Channels und da ist für jeden was dabei.

Wolfi Gassler (00:51:38 - 00:51:43)

Und das ist aber komplett open source in dem Fall auch. Also ist rein community driven.

Jana Aydinbas (00:51:43 - 00:52:14)

Genau, von der Community für die Community. Jeder kann sich so viel einbringen, wie er oder sie möchte. Und ich habe bis vor kurzem das Ride the Dogs Meetup Karlsruhe geleitet. Wir haben erst reale so Feierabend Treffen gemacht mit Fachvorträgen und anschließender Diskussion und sind dann während der Pandemie auf ein virtuelles Format umgestiegen und das ist dann aber ein bisschen eingeschlafen und deswegen haben wir uns jetzt verabschiedet.

Wolfi Gassler (00:52:14 - 00:52:30)

Und was wird da so präsentiert? Ich kenne ja Meetup sehr gut, aber ich habe noch nie irgendwie einen Vortrag zur Dokumentation gesehen, muss ich jetzt zu meiner Schande zugeben. Also hast du da mal irgendwie so einen Auszug aus Themen, die es da so gibt und die dort besprochen werden?

Jana Aydinbas (00:52:30 - 00:52:42)

Ja, ganz unterschiedlich. Also bei uns wurden Standards vorgestellt, Projekte aus dem Arbeitsalltag, es wurden Diskussionen geführt, ganz unterschiedlich.

Wolfi Gassler (00:52:42 - 00:52:48)

Aber es ist jetzt nicht so, dass man da irgendwie schöne Dokumentationen gemeinsam durchgeht oder sich zeigt.

Jana Aydinbas (00:52:48 - 00:52:55)

Nein, das war nicht das Thema, aber das ist tatsächlich eine häufige Frage in der Write the Dogs Community. Könnt ihr mir eure Lieblingsdoku nennen?

Wolfi Gassler (00:52:55 - 00:52:57)

Einfach Okay, was ist deine Lieblingsdoku?

Jana Aydinbas (00:52:57 - 00:53:14)

Meine jetzt nicht, aber dort häufig genannt wird die Stripedo, weil die super interaktiv ist. Und eine weitere, die häufig genannt wird, ist der Quickstart Guide von React. Der ist super gut strukturiert, der holt einen inhaltlich ab, führt einen thematisch weiter.

Andy Grunwald (00:53:15 - 00:53:32)

Stripe habe ich jetzt auch nicht zum ersten mal gehört als gutes Referenzbeispiel, kam schon von anderen Leuten auch auf. Ich habe leider noch nicht so viel mit Stripe gemacht, deswegen ich muss mir jetzt anscheinend mal einen guten Anwendungsfall suchen, damit ich endlich mal die Doku nutzen kann.

Wolfi Gassler (00:53:32 - 00:53:37)

Ich habe gedacht, wir haben wir haben einen Stripe Account an die jetzt für unseren Buy me a Coffee.

Andy Grunwald (00:53:37 - 00:54:22)

Ja, alle Leute können uns jetzt Kaffee ausgeben und Den Link findet ihr natürlich in den Show Notes. Kleine Werbung. Und diesen Kaffee reichen wir natürlich an all unsere Gäste weiter. Wenn wir Diana in diesem Fall mal irgendwann in Karlsruhe besuchen kommen, wenn sie mal wieder ein Ride the Dogs Meetup macht, dann reichen wir natürlich den Kaffee weiter. Das bedeutet an alle Hörerinnen und Hörern, ihr gebt nicht nur Wolfgang und mir einen Kaffee aus, sondern in diesem Sinne dann auch Jan. Du hattest gerade Ride the dogs als Community, als Inspiration und auch als vielleicht als Feedback Channel erwähnt. Gibt es denn noch andere, ich sag mal Bereiche im Internet, wo ich mir so ein paar, ich sag mal Best Practices klauen kann? Du hattest vorhin z.B. als einen Aufgabenpunkt für Technical Writer sogenannte Templates genannt. Also kann ich mir irgendwo Sachen klauen?

Jana Aydinbas (00:54:22 - 00:55:07)

Ja, und zwar gibt es das the Good Docs Project, da gibt es Templates und sowas ist immer gut gegen Schreibblockaden, dass man nicht bei null anfangen muss, sondern was ausfüllen kann. Die beschreiben auch Prozesse für die Dokumentationserstellung. Und geben Beispiele für die Anwendung der Templates. Das wäre noch eine gute Quelle. Die Write the Docs Community haben wir erwähnt. Da gibt es einen Documentation Guide. Das ist ein super umfassender Guide zu allen möglichen Themen, auch unter anderem in der Kategorie Beginner's guide to Writing Documentation. Also da werden die Fragen geklärt, warum sollte Dokumentation erstellt werden, was sollte da drinstehen? Und eine andere interessante Ressource ist Diataxis. Das ist ein Framework für Software Dokumentation. Das kann ich nur jedem empfehlen, sich mal zu informieren.

Wolfi Gassler (00:55:07 - 00:55:23)

Dann kann ich jetzt gleich einwerfen, weil ich die Zeit genutzt habe, in der Zwischenzeit Retype zu googlen. Retype ist ein Static Site Generator für Hilfe Seiten. Also auch das scheint ein cooles Framework zu sein, ohne dass ich es jetzt jemals verwendet habe, aber der Output hat mir zumindest gefallen.

Andy Grunwald (00:55:23 - 00:55:56)

Jana, was würdest du empfehlen für Leute, die sich jetzt mehr mit dem Berufsbild auseinandersetzen wollen? Die hören diese Podcast Episode, haben gesagt, ich möchte das endlich mal lernen. Wo? Klar, Write the Docs schaue ich mir an. Und jetzt habe ich mir die Dokumentation von Write the dogs. Ist das eigentlich so ein wiederkehrendes Ding? So wie Gnu Rekursion heißt es ja. Rekursion, genau. Gute Softwareentwicklerinnen und Softwareentwickler würden das wissen, ich nicht. Aber wo gehe ich denn weiterhin, wenn ich mich mit dem Berufsbild mal ein bisschen mehr tiefer beschäftigen möchte?

Jana Aydinbas (00:55:56 - 00:56:54)

Ich würde sagen, der Beruf des Technical Writers, der Technical Writerin steht allen offen. Es gibt auch Erhebungen von der TECUM, der Gesellschaft für technische Kommunikation, dass in Deutschland etwa Menschen im Bereich technische Doku arbeiten und rund 50 % davon haben eine formale Qualifikation. Ich würde sagen, es ist ein lernbares Handwerk und wenn man sich dafür interessiert, dann auf den genannten Seiten kann man sich informieren und ansonsten einfach Dokumentationserstellung üben. Und die Tools sind aber erstmal egal. Vielleicht erstellt ihr für ein privates Projekt Dokumentation und vielleicht fällt es euch aber auch leichter, Dokumentation zu überarbeiten. Dann müsst ihr nicht bei null anfangen. Und das wäre auch eine Möglichkeit, sich zu überlegen, was kann man denn besser machen an der Dokumentation? Und eine wieder andere Möglichkeit wäre, etwas zu standardisieren. Ein privates Knowledge Management System, die eigenen Kochrezepte, was auch immer. Eine Informationsarchitektur erstellen und einheitlich umsetzen.

Wolfi Gassler (00:56:55 - 00:57:03)

Also standardisieren im Sinne von ich definiere eine Struktur für mich, wie das sinnvoll ablegen kann, mehrere Dinge, die gleich oder ähnlich sind.

Jana Aydinbas (00:57:03 - 00:57:11)

Genau. In diesem Fall wäre man selbst die Zielgruppe und dann würde schauen, für sich selber schauen, wie das am besten alles präsentiert werden könnte.

Wolfi Gassler (00:57:11 - 00:57:58)

Ich finde es ja auch super, irgendwo eine Dokumentation zu verbessern oder anzupassen, weil es gibt eigentlich nichts Schöneres, wenn man ein Open Source Projekt hat und man sieht dann plötzlich Contributors, die irgendwas verbessern oder ändern und wenn es nur ein Tippfehler ist und ihr habt es auch bei so vielen anderen Leuten schon gesehen, die sind einfach so was von glücklich, weil da nur ein Typo ausgebessert wird. Also alleine diese Motivation, die man da anstößt, das ist genial. Und wenn man dann selber auch noch einen Lerneffekt hat, dass man einfach mit Dokumentation mehr zu tun hat, damit in Kontakt tritt, das verbessert und auch vielleicht sieht, warum man etwas verbessert, warum man etwas besser machen kann und wie man es besser machen kann. Das ist glaube ich für alle Beteiligten super. Also es kann ich nur voll unterschreiben, macht die Open Source Welt glaube ich einfach besser und glücklicher in dem Fall.

Jana Aydinbas (00:57:58 - 00:58:38)

Auch die Mitwirkung in Open Source Projekten wird auch oft genannt, um Erfahrungen in Dokumentationserstellung zu sammeln, aber ich finde das gar nicht so einfach. Man muss ja erstmal von dem Open Source Projekt akzeptiert werden als Contributor und gerade im Technical Writing benötigt man ja einiges an Ressourcen. Die Recherche haben wir vorhin schon angesprochen, da muss einem ja jemand ganz viele Informationen zur Verfügung stellen oder Zeit für Recherchegespräche. Was es aber gibt, ist auch wieder im Write the Dogs Lab, da gibt es einen Channel, der heißt Community Help Wanted, untersuchen gezielt Open Source Projekte nach Unterstützung und denen ist dann auch klar, was sie dazu beitragen müssen, damit das klappen kann.

Wolfi Gassler (00:58:38 - 00:58:55)

Es gibt auch ganz oft so Issues, die irgendwie getaggt sind für Anfänger oder Help Wanted oder so, also da kommt man oft auch näher hin. Aber wir hatten mal mit Severin ein Interview, Andy, du kannst die Episodennummer natürlich auswendig, so wie ich dich kenne, 101.

Andy Grunwald (00:58:55 - 00:58:58)

Paar gequetschte 101, 102 irgendwie sowas, der.

Wolfi Gassler (00:58:58 - 00:59:43)

Ja auch verantwortlich ist für die Dokumentation von Open Telemetrie. Danke Andi. Und der auch immer total happy ist, wenn wenn ihn irgendwer unterstützt und wenn die Community da mithilft. Also ich glaube schon, dass die die meisten Projekte eigentlich froh sind, wenn sie Unterstützung bekommen, aber wie du richtig sagst, wenn man natürlich eines erwischt, wo man dann sofort abgelehnt wird, das ist natürlich auch wahnsinnig schlechte Erfahrung. Also vielleicht das im Vorhinein abchecken ist immer gut. Aber Jana noch eine Frage, wenn wenn ich das jetzt nicht studiert habe, so wie du, wie komme ich denn dann überhaupt in dieses Berufsfeld rein? Glaubst du, habe ich da eine Chance, wenn ich mich irgendwo bewerbe, wenn ich nur als Überzeugung oder mit ein paar Dokumentationen, die ich bisher gemacht habe im Open Source Bereich, kann ich mich dann schon trauen, in das Berufsfeld einzusteigen?

Jana Aydinbas (00:59:43 - 01:00:22)

Ja, das kann funktionieren. Also zum einen haben viele Dokumentationen im Rahmen ihrer beruflichen Tätigkeit geschrieben, ohne eben die Berufsbezeichnungen Technical Writer in gehabt zu haben. Und diese Projekte kann man dann ja beschreiben im Lebenslauf oder und es wird häufiger nachgefragt, dass man ein Portfolio braucht und dann kann man im Portfolio auch beispielsweise seine privaten Projekte verwenden und er erklärt dort den Erstellungskontext und den Prozess. Und das kann genauso gut funktionieren wie ein berufliches Projekt, was oftmals mit einer neuen belegt ist und gar nicht verwendet wird.

Andy Grunwald (01:00:22 - 01:00:38)

Somit sind wir auch schon am Ende dieser Episode. Ich finde es immer wieder faszinierend, wie wir mit initial gedachten kleinen Themen doch wieder so lang und so tief ins Detail eingehen können. Ich finde es faszinierend.

Wolfi Gassler (01:00:38 - 01:00:43)

Jetzt Moment, da arbeiten Leute in dem Bereich und du sagst, es ist ein kleines Thema.

Andy Grunwald (01:00:43 - 01:01:53)

Ja, aber heute habe ich unter anderem gehört, dass der Job von Günter Wallraff gar nicht so weit entfernt ist vom Technical Writing, wenn man von Jira investigativen Journalismus ausgeht. Kleiner Gag. Faszinierend. Vielen lieben Dank. Ich habe wirklich was mitgenommen. Also besonders diese fünf oder sieben Cs merkst du, ich muss da noch mal einsteigen. Ich glaube, die Checkliste, die packe ich mir auch mal als Post jetzt hier an den an den an den Bildschirmen das nächste Mal, wenn ich eine Dokumentation schreibe. Und dann auch dieses Detaxis Framework, das fand ich ganz cool. Ich bin gerade mal kurz auf die Webseite gegangen, wirklich tutorials für learning how to Guides mit Zielen, Referenzen. Also Wahnsinn. Und ich bin gerade mal durch die Ride the Dogs Talks gescrollt. Ich weiß gar nicht mehr, ob ich meinen Netflix Account noch brauche, weil ein paar haben wirklich, wirklich gut geklungen. Ja, ich weiß nicht, ob ich mich jetzt beschweren soll, da ich in Zukunft keine Zeit mehr haben soll oder Danke sagen soll, dass du mich in diese neue Welt eingeführt hast. Dann ich sage einfach mal danke. Vielen Dank, Diana. Aber möchtest du noch irgendwas zum Abschluss sagen?

Jana Aydinbas (01:01:53 - 01:02:17)

Ja, ich danke euch für die Einladung. Ich freue mich sehr, dass ihr was mitnehmen konntet. Wenn ihr Zuhörer innen habt, die Lust haben, mit mir zusammenzuarbeiten, können die sich gerne bei mir im Right the Dog Slack oder über LinkedIn melden. Wir suchen neue Kolleginnen, und zwar Technical Writerin, aber auch z.B. java Entwicklerinnen und auch unabhängig davon, die ihr gerne mit mir Kontakt aufnehmen. Ich freue mich drüber.

Wolfi Gassler (01:02:17 - 01:02:23)

Wir setzen die ganzen Links und die Kontaktmöglichkeiten natürlich auch in den Shownotes. Dann kann man sich einfach bei dir melden.

Andy Grunwald (01:02:23 - 01:02:35)

An alle, die jetzt heute noch keine Dokumentation geschrieben haben, hopp Hopp, jetzt aber. Und somit bis zum nächsten Mal. Nächsten mal gibt es einen Test. Wie viel Dokumentation habt ihr jetzt geschrieben? Danke Diana für deine Zeit und bis bald. Tschüss.

Wolfi Gassler (01:02:35 - 01:02:36)

Danke Jana.

Jana Aydinbas (01:02:36 - 01:02:36)

Danke euch.