Lessons Learned: Dokumentation

Von vielen vernachlässigt, aber sehr wichtig: Dokumentation. Zusammen mit Gina Häußge (Maintainerin des OctoPrint-Projekts) und Tanja Roth (Project Manager Technical Documentation bei SUSE) besprechen wir Arten der Dokumentation, Technical Writing und zahlreiche Tools, die das Pflegen von Dokumentationen erleichtern.

Intro

• Ginas Webseite: https://foosel.net
• OctoPrint-Webseite: https://octoprint.org/
• Gina im OctoPrint-Interview in FOL #88: https://focusonlinux.podigee.io/88-octoprint
• Tanjas LinkedIn Profil: https://www.linkedin.com/in/tanja-roth/
• Weitere Profile von Tanja:
  • https://opensource.com/users/taroth
  • https://www.suse.com/c/the-brains-behind-the-books-tanja-roth/
  • https://tcworldconference.tekom.de/conference-program/speakers/speaker/roth-tanja
• Buchtipp: "Technisches Schreiben", Peter Rechenberg
• DOCUMENTATION-1256 - How to Write Technical Documentation that Actually Works (SUSECON 2024): https://youtu.be/VgYsPmKXJ_E

Tools

• Sphinx: https://www.sphinx-doc.org/
• reStructuredText: https://docutils.sourceforge.io/rst.html
• mkDocs: https://www.mkdocs.org/
• DocBook: https://docbook.org/
• AsciiDoc: https://asciidoc.org/
• DAPS (DocBook Authoring and Publishing Suite): https://github.com/openSUSE/daps
• Doc-Kit (zum Initialisieren und Aktualisieren von DAPS-basierter Dokumentation): https://github.com/openSUSE/doc-kit
• Editieren der SUSE-Dokumentation mit dem VSCode Editor:
  https://github.com/openSUSE/suse-vscode-doc
• SUSE Vale Styleguide Extension für den VSCode Editor:
  https://github.com/openSUSE/vscode-suse-vale-styleguide
• Uyuni-Dokumentation: https://github.com/uyuni-project/uyuni-docs
• SUSE Dokumentationsportal: https://documentation.suse.com
• Read the docs: https://about.readthedocs.com/
• OctoPrint-Dokumentation:
  • https://docs.octoprint.org (page)
  • https://github.com/OctoPrint/docs.octoprint.org (repository inkl. Build Automation)
• Plausible: https://plausible.io/
• Matomo: https://matomo.org/