Docs-as-Code: Creating Professional Software Documentation with Static Site Generators

Tutorial
Softwaredokumentation

Valerie Schipka
- Theobald Software
Maia Reichert-Baisch
- Theobald Software

Inhalt

Managing documentation in fast-paced development environments is challenging, but the Docs-as-Code approach offers a modern solution by applying software development practices to documentation.

This session introduces you to the fundamentals of static site generators (SSGs) and demonstrates how open source tools like MkDocs can turn plain text into professional, user-friendly documentation websites. We will walk you through the whole setup in a live tutorial, from installation to the integration of your documentation into a continuous delivery environment. By the end of this tutorial you will have an up and running documentation website.

Whether you're a technical writer, developer, or part of an agile team, you will leave this session with practical insights on how to create cost-effective, agile documentation solutions using only open source tools.

To follow along with the hands-on portion of the tutorial:

Set up a GitHub account
Download Python (3.8 or higher)
Download Git
Download Visual Studio Code

Das lernen Sie

How to get started with docs-as-code
Implement a docs-as-code approach using MkDocs and the Material theme
Automate the publishing process in a continuous delivery environment
Benefits and limitations

Vorkenntnisse

A basic familiarity with markup languages — especially Markdown — will help participants follow along, as it's the primary format used in the session. Additionally, a general understanding of version control concepts (e.g., using Git) will provide useful context for how MkDocs integrates into the continous delivery environment.

To follow along with the hands-on portion of the tutorial:

- Set up a GitHub account

- Download Python (3.8 or higher): www.python.org/downloads/

- Download Git: git-scm.com/downloads

- Download Visual Studio Code: code.visualstudio.com/download

We will install everything together during the live tutorial.

Referent:innen

Valerie Schipka

Theobald Software

Zum Profil

Biografie

Valerie Schipka machte zunächst ihren Abschluss in Mathematik und Naturwissenschaften an der Hochschule Darmstadt und arbeitete einige Jahre als Applikationsingenieurin, bevor sie Ihre Leidenschaft für die Technische Dokumentation entdeckte. Als Quereinsteigerin mit technischem Hintergrund ist sie bei Theobald Software nicht nur für die Dokumentationsinhalte einer breiten Produktpalette verantwortlich, sondern auch für die Wartung und Optimierung von Dokumentationsportalen. Dabei setzt sie stets auf neue Technologien und Trends - vor allem aus dem Entwicklungsbereich -, um Benutzern Informationen so verständlich und einfach wie möglich zur Verfügung zu stellen.

Valerie Schipka first earned her degree in Mathematics and Natural Sciences at the University of Applied Sciences in Darmstadt and worked for several years as an application engineer before discovering her passion for technical documentation. As a gifted career changer with a technical background, she is not only responsible for the documentation content across a broad product range, but also for maintaining and optimizing documentation websites at Theobald Software. She consistently embraces new technologies and trends to present information to users as clearly and accessibly as possible.

Maia Reichert-Baisch

Theobald Software

Zum Profil

Biografie

Maia Reichert-Baisch ist aktuell Information Security Managerin bei Theobald Software, nachdem sie dort bereits als Technische Redakteurin tätig war. Davor war sie als Technical Writerin bei Roche - RDA und bei cognitas (Etteplan) aktiv. Mit einem Master in Kommunikation und Medienmanagement (HS Karlsruhe) bringt sie ein tiefgehendes Know-how in technischer Dokumentation und IT-Sicherheit mit.

Maia Reichert-Baisch is currently the Information Security Manager at Theobald Software, having previously worked there as a Technical Writer. Prior to that, she held Technical Writer positions at Roche - RDA and at cognitas (Etteplan). With a Master's degree in Communication and Media Management, she brings in-depth expertise in technical documentation and IT security.

zurück