#125 Die Kunst der technischen Dokumentation mit Jana Aydinbas
Engineering Kiosk
Bedeutung der Dokumentation bei Open Source Projekten
Die Sprecher diskutieren die Relevanz umfangreicher Dokumentation, einer unterstützenden Community und verständlicher Tutorials für die Evaluation von Open Source Projekten. Auch die Herausforderungen und Vorteile von verschiedenen Tutorials sowie die Rolle von Write the Docs als offene Community für Dokumentatoren werden erläutert.
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
Unsere aktuellen Werbepartner findest du auf https://engineeringkiosk.dev/partners
Das schnelle Feedback zur Episode:
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
Gerne behandeln wir auch euer Audio Feedback in einer der nächsten Episoden, einfach die Audiodatei per Email an stehtisch@engineeringkiosk.dev.
Links
- Jana Aydinbas auf LinkedIn: https://www.linkedin.com/in/jana-aydinbas/
- Google Season of Docs: https://developers.google.com/season-of-docs?hl=de
- Vortrag: Daniele Procida - Always complete, never finished: https://www.writethedocs.org/videos/portland/2021/always-complete-never-finished-daniele-procida/
- Write the Docs Website: https://www.writethedocs.org/
- Write the Docs Slack: https://www.writethedocs.org/slack/
- Write the Docs Guide: https://www.writethedocs.org/guide/writing/beginners-guide-to-docs/
- Write the Docs Meetups: https://www.writethedocs.org/meetups/
- Diátaxis (Framework für Softwaredokumentation): https://diataxis.fr/
- The Good Docs Project (Templates, Prozesse und Beispiele): https://thegooddocsproject.dev/
- 5C’s of Technical Writing: https://medium.com/technical-writing-is-easy/5cs-of-technical-writing-7e5039917801
- Stripe Documentation: https://docs.stripe.com/
- React Quickstart Guide: https://react.dev/learn
- tekom “Was ist technische Kommunikation?”: https://www.tekom.de/technische-kommunikation-das-fach/was-ist-technische-kommunikation
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
The AI-powered Podcast Player
