Lessons Learned: Dokumentation

12/07/24 • 60 min

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:
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/

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:
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/

Vorherige Episode

Open Source-Lizenzen

Insbesondere in den letzten Jahren waren sie in aller Munde: Open Source-Lizenzen. Doch welche gibt es und worin unterscheiden sie sich? Welche sind kompatibel zueinander? Welche Implikationen haben sie auf Forks? Diesen Fragen gehen wir zusammen mit Jurist Udo Meisen auf den Grund.

Einführung

GNU Philosophy: https://www.gnu.org/philosophy/free-sw.de.html
Open Source Initiative: https://opensource.org/

Lizenzen

Wikipedia - GNU General Public License: https://de.wikipedia.org/wiki/GNU_General_Public_License
Wikipedia - GNU Lesser General Public License: https://de.wikipedia.org/wiki/GNU_Lesser_General_Public_License
Wikipedia - GNU Affero General Public License: https://de.wikipedia.org/wiki/GNU_Affero_General_Public_License
Einige AGPL-lizenzierte Anwendungen: https://en.wikipedia.org/wiki/List_of_software_under_the_GNU_AGPL
Wikipedia - BSD-Lizenz: https://de.wikipedia.org/wiki/BSD-Lizenz
Einige BSD-lizenzierte Anwendungen: https://en.wikipedia.org/wiki/Category:Software_using_the_BSD_license
Wikipedia - Apache-Lizenz: https://de.wikipedia.org/wiki/Apache-Lizenz
SIL OFL: https://openfontlicense.org/
Creative Commons: https://creativecommons.org/
Creative Commons-Assistent: https://chooser-beta.creativecommons.org/
OpenVerse-Bilddatenbank: https://openverse.org/
Computerwoche - Microsofts KI-Chef: "Frei zugängliche Webinhalte sind Freeware": https://www.computerwoche.de/article/2835091/frei-zugaengliche-webinhalte-sind-freeware.html
TDM Reservation Protocol: https://www.w3.org/community/reports/tdmrep/CG-FINAL-tdmrep-20240510/
GPLv3-Kompatibilität: https://gplv3.fsf.org/wiki/index.php/Compatible_licenses
XKCD 2347 - Dependency: https://xkcd.com/2347/
European Union Public Licence: https://de.wikipedia.org/wiki/European_Union_Public_Licence
Code Europa: https://code.europa.eu/

Tool- und Medientipps

Sag mal du als Richterin: https://www.audible.de/ep/sag-mal-du-als-richterin
Zeit Verbrechen-Podcast: https://www.zeit.de/serie/verbrechen
Rechtsbelehrung-Podcast: https://rechtsbelehrung.com/
WebJustiz-Blog: https://webjustiz.de
spdx-Tools: https://spdx.dev/use/spdx-tools/
Überwachungsstelle des Bundes für Barrierefreiheit von Informationstechnik: https://www.bfit-bund.de/

Nächste Episode

Podcasting unter Linux

Ein weit verbreiteter Mythos ist, dass Linux unter kontinuierlichen Sound-Problemen leidet. Dabei lassen sich mit Linux auch hochwertige Audio-Produktionen anfertigen, wie uns der langjährige Podcaster Ingo Ebel bestätigt.

Intro