Dokumentation in der Softwareentwicklung - The good, the bad and the ugly

JAX Mainz 2022

@jaxcon

Pascal Euhus

Software Architect

Pascal Euhus

  • Software Architect

  • Lazy

  • Cloud Enthusiast

  • Boulderer

pascal

Covid 19 → New Work

  • Work from home

  • No 9-5 availability

  • Meetings, meetings, meetings (online)

The code is the best documentation.

— Some Developers

The code doesn’t tell the whole story.

— Simon Brown

Simple workflow

Diagram

Definition of Done?!

  • Code compiles

  • Pipeline is green

    • Linter passed

    • Tests passed

    • (Test coverage)

  • (Acceptance criteria met)

Acceptance criteria?!

  • Functional

    • Works as intended

  • Non functional

    • Quality scenarios

    • Security

    • Documentation

    • …​

Diagram

Reasons

  • We have no time

  • I don’t like

  • No value on outcome

Why Documentation?

  • Knowledge persistence

  • Which problem(s) do we solve here?

  • Understand decisions (Context)

Asking

Knowledge persistence

  • What if a person leaves the team?

  • What if a person leaves the company?

Exit

Wer schreibt, der bleibt

— Unknown

Understanding the problem

  • Still existing?

  • Still relevant to business?

Issue

Understanding the context

  • Still some constraints?

  • Are there better solutions?

NoClue

Document with fun

  • Use the tool(s) you like most

  • Automate

  • Ease documentation review

  • Set a clear scope

    • what

    • for whom

Fun

7 Smells of Documentation

Non existent

Document

Incomplete

Review + Support

Legacy

Content-Strategy

Lazy / Tangled

Scope

Redundancy

Centralize and link

Communication and Language

Ubiquitous Language

Accessibility

Transparency/ Simplify access

Where to store documentation

Configuration files Source Code Powerpoint Word Git commit Non existent Jira Confluence Wiki Drive Documents The Developers Brain AsciiDoc Markdown

Doc-as-Code

Antora

site:
  title: Antora Demo Site
  url: https://antora.gitlab.io/demo/docs-site
  start_page: component-b::index.adoc
content:
  sources:
  - url: https://gitlab.com/antora/demo/demo-component-a.git
    branches: HEAD
    edit_url: false
  - url: https://gitlab.com/antora/demo/demo-component-b.git
    branches: [v1.0, v2.0, main]
    start_path: docs
ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true

Antora Component

name: component-b
title: Component B
version: 2.5
prerelease: -beta.1
nav:
- modules/ROOT/nav.adoc
- modules/module-one/nav.adoc

Documentation = ❤

Someone already did it

TL;DR; documentation

  • Know your audience

  • Less redundancy

  • Avoid ambiguity

  • Review process

  • Establish standards

  • Continuously update

  • Clearly arranged diagrams

References

Thank you

Slides at pascal.euhus.dev/slides

Meet Pascal