JBake

Gelesen: Sketchnotes in der IT von Lisa Maria Moritz

Thu, 9 Apr 2026 17:49:23 +0000

Gerade richtig zum Wochenende landete das Buch Sketchnotes in der IT in meinem Briefkasten. Ich bewundere schon länger die Sketchnotes von Lisa und hoffe immer wieder, dass sie in einem meiner Vorträge sitzt und ich im Anschluss einen Tweet mit der graphischen Zusammenfassung auf ihrem Twitter-Kanal @Teapot4181 bewundern kann.

Jetzt ist ihr Buch draußen und ich habe das schöne Wetter am Wochenende genutzt, um es zu verschlingen.

Das Buch gliedert sich hauptsächlich in zwei Teile. Im ersten Teil erklärt Lisa die Grundlagen ihrer Sketchnotes und auch ihre Tipps und Tricks um erfolgreich starten zu können.

Im zweiten Teil öffnet Lisa für uns ihre kreative Bibliothek an Symbolen, die sie für ihre IT-Sketchnotes benutzt. Darunter befinden sich viele clevere Icons (ich liebe die Symbole für Backend und Frontend!), die mir bei meinen ersten Gehversuchen auch gleich gut weiter geholfen haben.

Am Spannendsten fand ich aber die Argumentation, dass Sketchnotes die Konzentration fördern und die visuellen Notizen sich viel besser nachschlagen lassen. Dem kann ich nach der Lektüre nur zustimmen.

Allen, die ihren Lernhunger visuell unterstützen wollen, kann ich das Buch empfehlen!

Note	auf dieser Seite verwende ich affiliate Links um meine Website damit zu finanzieren. Danke für Dein Verständnis ♥.

Peter Naur, Stochastic Parrots, and the Future of Software Architecture: My Thoughts from Software Architecture Gathering 2024

Fri, 5 Dec 2025 00:00:00 +0000

Contents

A Conference Between Tradition and Transformation
The Forgotten Foundation: Peter Naur’s Mental Model
- Semantic Anchors: The Bridge Between Humans and Machines
#TODO: Replace Human Coding With AI?
The Stochastic Parrot: Understanding Limitations
The Fish Bowl: Human Intelligence vs. Artificial Intelligence
arc42 in Education: A Conversation with Claudine Allen
My Core Theses
The Future of Software Architecture

Last week, I had the honor of speaking before an international audience at the iSAQB’s Software Architecture Gathering in Berlin. The conference offered not only technical depth but also philosophical perspectives on the future of our discipline in the age of GenAI.

A Conference Between Tradition and Transformation

Peter Hruschka opened the conference with his keynote – without any mention of GenAI. A deliberate contrast to what would follow. Stefan Toth laid the foundation with his talk for my own presentation about the future of software architecture and development with GenAI.

The Forgotten Foundation: Peter Naur’s Mental Model

When I asked who was familiar with the name Peter Naur, only about 3 hands went up in the room. One of them was Avraham Poupko – more on that in a moment. This was a surprising moment because Naur’s concept of the "mental model" from his essay "Programming as Theory Building" (1985) is more fundamental than ever.

Naur argued that a program is not its source code, but rather a shared mental construct that lives in the minds of the people who work on it. The code is merely a lossy representation of this theory. In an era where LLMs can generate code, this distinction becomes critical: Who builds and maintains the mental model when AI writes the code?

Semantic Anchors: The Bridge Between Humans and Machines

My second passion topic is semantic anchors for prompt optimization. When we work with LLMs, we need precise ways to communicate our mental model. Semantic anchors create this connection – they are the interface between human understanding and machine generation.

#TODO: Replace Human Coding With AI?

Avraham Poupko later delivered a fascinating deepening of the topic. In his talk "#TODO: Replace Human Coding With AI," he presented his insights in an unprecedented chain of reasoning. His conclusions picked up on Naur’s concepts and carried them forward into the era of AI-assisted development.

The central question: If LLMs can write code, what makes humans essential in the development process? The answer lies precisely in Naur’s theory: building, understanding, and maintaining the mental model – something that LLMs fundamentally cannot accomplish.

The Stochastic Parrot: Understanding Limitations

Vaughn Vernon brought us back down to earth with his talk about the "stochastic parrot." He emphasized the mathematics behind the models and explained from the LLMs' functioning what they do well and what they do poorly.

The term "stochastic parrot" comes from the critique that LLMs probabilistically link words without truly understanding their meaning. For us architects, this means:

✅ LLMs are excellent at pattern recognition and code generation
❌ LLMs don’t understand the "why" behind architectural decisions
✅ They can create and search documentation
❌ They cannot build genuine theory in Naur’s sense

Vaughn’s mathematically grounded perspective helped us understand the limitations and develop realistic expectations.

The Fish Bowl: Human Intelligence vs. Artificial Intelligence

In the evening, the discussion deepened in the Fish Bowl "Software Architecture – Is It About Human Intelligence or Artificial Intelligence?" with Vaughn Vernon, Cheryl Hung, Avraham Poupko, Eberhard Wolff, and participants from the audience.

The debate crystallized: It’s not "or" but "and" – but with clear role distribution. Human intelligence is irreplaceable in building the mental model, making architectural decisions under uncertainty, and understanding business contexts. AI becomes a powerful tool, an accelerator, but not a replacement.

arc42 in Education: A Conversation with Claudine Allen

A particular highlight was the talk by Claudine Allen from Jamaica. She reported how she teaches her students to use AI as a research and brainstorming tool for architecture work. She casually mentioned using arc42 in her work with students.

I was able to deepen this topic in the subsequent interview with her, which you can follow up on at software-architektur.tv. Claudine’s approach impressively shows how the next generation of architects learns to use AI as a collaborative design partner – without forgetting the fundamental principles of good architecture work.

Her students learn:

To use LLMs for research and exploration
To critically question the results
To build the mental model themselves
To document in a structured way with arc42

My Core Theses

After this intensive conference, the following theses crystallize for me:

1. The Mental Model Remains Central

Naur’s concept is more important than ever. While LLMs generate code, we humans must build and maintain the mental model. This is the non-delegable core competency of the software architect.

2. Semantic Anchors as Key Technology

The way we communicate with LLMs determines the quality of the results. Semantic anchors – precise, context-rich prompts – are the bridge between our mental model and AI support.

3. Understand, Don’t Just Generate

The stochastic parrot can reproduce impressive patterns, but it doesn’t understand. We need to know the limitations and work accordingly. LLMs are tools, not thinking partners.

4. Education Must Adapt

Claudine’s work shows the way: we must teach the next generation to use AI effectively without losing the ability to think independently.

The Future of Software Architecture

We stand at a fascinating turning point. GenAI and LLMs will fundamentally change the way we develop software. But they don’t make the role of the architect obsolete – on the contrary.

The architect of the future:

Uses LLMs as powerful tools
Builds and maintains the mental model of the system
Makes decisions based on context not accessible to AI
Understands the limitations of the technology
Communicates effectively with both machines and humans

The Software Architecture Gathering 2024 showed: We need both the philosophical depth of a Peter Naur and the practical understanding of AI limitations. The synthesis of these perspectives will shape the software architecture of the future.

Further Resources:

Peter Naur: "Programming as Theory Building" (1985)
My interview with Claudine Allen at software-architektur.tv
arc42 Template: arc42.org

What do you think? How do you integrate LLMs into your architecture work without losing sight of the mental model?

#SoftwareArchitecture #GenAI #LLM #arc42 #iSAQB #SAG2024 #PeterNaur #AI #MachineLearning #SoftwareDevelopment

My MCP Setup

Thu, 3 Jul 2025 00:00:00 +0000

Oft werde ich gefragt, was für Tools ich bei der Arbeit mit LLMs verwende. Hier ist meine Liste.

Als Chat nutze ich gerne Claude Desktop oder Claude Code. Auch der Amazon Q Developer CLI ist spannend und Gemini CLI ist installiert, aber nicht getestet.

IDE basierte Systeme empfinde ich nicht so spannend. Eine Zusammenarbeit über das File-System reicht mir aus. Dabei greift der Chat über ein in einen Container gemountetes Working-Directory direkt auf das Projekt zu, das ich in einer IDE offen habe.

Dennoch habe ich auch Cursor als spannendes Experiment installiert.

MCP Servers

Filesystem & Bash

Für Experimente ist ein Filesystem-MCP und ein Bash-MCP äussert nützlich. Ich habe mir beide von Claude erstellen lassen. Sie laufen in einem Container mit gemountetem Working-Directory.

In der Bash sind wichtige Tools wie Git mit Account und gh installiert.

Mein Filesystem-MCP hat eine Besonderheit. Wenn das LLM einen Folder oder ein File anlegt, muss es angeben, wofür dieser Folder oder das File dient. Schaut es sich in einer anderen Session die Files wieder an, bekommt es diese Meta-Daten auch wieder angezeigt.

Codeinterpreter

Durch den Einsatz der Bash fällt der Codeinterpreter weg. Das LLM kann alles direkt über die Bash erledigen.

Kroki

Experimentell nutze ich ein Kroki-MCP, welches Diagramme generieren kann. Ziel ist es, die Diagramme zuverlässig und in hoher Qualität zu erzeugen.

gitmcp.io

Um den Knowledgegap der Modell zu überbrücken nutze ich gitmcp.io . Um dem LLM die Dokumentation eines GitHub Projekts zur Verfügung zu stellen, muss man einfach nur in der URL github.com gegen gitmcp.io ausgetauscht werden. Das Ergebnis ist eine URL für einen entsprechenden Remote-MCP-Server.

Sequential-Thinking

Die Todo-Liste für das LLM. Claude nutzt diesen MCP-Server gerne, um seine Gedanken zu strukturieren.

      "Sequential-Thinking": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-sequential-thinking"
        ]
      }

GitHub

GitHub hat schon früh einen eigenen offiziellen MCP Server veröffentlicht. Damit kann das LLM quasi alle Operationen durchführen. Issues lesen und verändern, Forken, Files ändern, PR erstellen.

Leider nutzt Claude momentan of dieses Tool, um Files zu editieren, ohne sie lokal zu testen.

Der Umgang mit dem Git-Flow fällt Code auch nicht ganz leicht, weshalb ich ihm weitere Infos mitgebe:

### Git-Workflow:

✅ Richtig: main → branch → commit → push → PR
✅ starte einen neuen Branch für einen Bugfix immer als Feature-Branch vom Main-Branch
❌ Falsch: Parallele Branches ohne Synchronisation
✅ entscheide, ob ich claude als co-authored-by nenne

Achte immer auf folgendes, wenn Du mit Forks arbeitest
* Fork-Status prüfen
* Bei Bedarf synchronisieren
* Dann Branch + PR erstellen

Wenn Du mit source code arbeitest, sind wir immer unter versionskontrolle. Du brauchst keine Backup-Files anzulegen, sondern solltest mit commits arbeiten.

Da ich nicht möchte, dass Claude unter meinem Account arbeitet und somit Zugriff auf alles hat, habe ich einen neuen Account angelegt. Das war eine gute Entscheidung. So kann ich jederzeit sehen, was generiert worden ist. Claude hat keinen direkten Zugriff auf meine Projekte und muss deshalb immer erst Forken und dann einen PR erstellen, den ich natürlich erst einem Review unterziehe.

      "github": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-e",
          "GITHUB_PERSONAL_ACCESS_TOKEN",
          "ghcr.io/github/github-mcp-server"
        ],
        "env": {
          "comment": "Raif Mueller Account",
          "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
        }
      }

playwright: Augen für das LLM

Beim Arbeiten mit den LLMs ist es wichtig immer einen Feedback-Loop aufzubauen, damit das LLM eigenständig arbeiten kann. Ein einfacher Weg für ein visuelles Feedback ist ein Browser.

playwright-mcp von Microsoft ermöglicht es dem LLM nicht nur einen Browser fernzusteuern, sondern auch Screenshots zu "sehen".

Damit kann das LLM automatische visuelle Tests einer Website durchführen und auch generierte Bilder über die Darstellung im Browser verifizieren.

Responsible Vibe

Oliver Jägle hat sich Gedanken gemacht, wie man das LLM dazu bringen kann, einen ordentlichen Entwicklungsprozess einzuhalten. Herausgekommen ist sein Responsible Vibe MCP.

"responsible-vibe-mcp": {
  "command": "npx",
  "args": ["responsible-vibe-mcp"]
}

Table of Contents

MCP Servers

Richtig arbeiten mit dem LLM

Wed, 8 Jan 2025 00:00:00 +0000

In vielen Demos sehe ich, wie Jemand mit Tools wie Github Copilot zu Code Tests erzeugen lässt. Das geht so schön einfach mit der Maschine und schnell hat man 100% Code-Coverage.

Der Ansatz ist aber auf so vielen Ebenen falsch…

Development Driven Testing?

Wollten wir nicht Test-Driven-Development machen? Wenn wir Tests zum Code schreiben, laufen wir Gefahr, dass wir die innere Mechanik unseres Codes testen und nicht das Verhalten! Wir sehen, was der Code macht und fangen an genau dafür Tests zu schreiben.

Ein falsches Verhalten im Edge-Case? Der Test fixiert den Bug!

Eine bestimmte Implementierung? Der Test, der die Implementierung testet und nicht das Verhalten, wird später ein Refactoring erschweren!

White-Board-Development

Aber der wichtigste Grund, nicht die Tests für den Code schreiben zu lassen ist, was ich als White-Board-Development bezeichne.

Wenn Du einen Algorithmus an einem Whiteboard entwerfen sollst, wie hoch ist die Wahrscheinlichkeit, dass der Code auf Anhieb fehlerfrei läuft? Genau - sehr gering. Aber von der Maschine erwarten wir es!

Wie gehen wir stattdessen vor? Wir nutzen unsere Lieblings-IDE und führen den Code aus, bemerken den ersten Syntax-Fehler und verbessern den Code. So iterieren wir, bis der Code läuft.

Ein LLM kann das über function-calling auch. Es muss nur das richtige Tool zur Verfügung gestellt bekommen. Im Fall von ChatGPT ist das der Python Code Interpreter

Table of Contents

Development Driven Testing?
White-Board-Development

Elgato Prompter: 2 Überraschungen, die du kennen musst 🎥🖥️

Fri, 18 Oct 2024 00:00:00 +0000

Note	Links sind Affiliate-Links

Letzte Woche habe ich mir den Elgato Prompter zugelegt. Elgato ist bekannt für seine Qualität – und entsprechende Preise. Die Erwartungen waren hoch, insbesondere aufgrund des eingebauten Bildschirms mit USB-C-Anschluss. Doch ich wurde schnell überrascht, nicht nur im positiven Sinne.

DisplayLink statt DisplayPort – Ein unerwarteter Stolperstein 🔌

Zunächst hätte ich erwartet, dass der Bildschirm über den nativen DisplayPort des USB-C-Anschlusses läuft. Stattdessen wird er jedoch über DisplayLink angesteuert, ein Protokoll, das zusätzliche Treiber erfordert. Die Installation dieser Treiber verlangt Administrationsrechte, die in Unternehmensumgebungen nicht immer zur Verfügung stehen. Noch schlimmer: Abhängigkeit von Treibern bedeutet auch, dass ein neues Betriebssystem und nicht mehr gepflegte Treiber das Produkt irgendwann unbrauchbar machen könnten. Da setze ich lieber auf gesetzte Standards.

Die Enttäuschung über die Auflösung 🧱

Ein weiterer überraschender Punkt war die Auflösung des Bildschirms: Sie liegt bei nur 1024 x 600 Pixeln. Für meine Hauptanwendung, Präsentationen auf dem Prompter anzuzeigen, führt das zu einem Problem. Der Bildschirm kann nicht direkt geteilt werden, da die schlechte Auflösung die Qualität beeinträchtigt und Aufnahmen darunter leiden würden.

MacOS vs. Windows – Ein Skalierungskrieg 🍏🪟

Die Sache wird noch komplexer, wenn man den Unterschied zwischen MacOS und Windows betrachtet. Unter MacOS gibt es nur die native Bildschirmauflösung, ohne Möglichkeit einer individuellen Skalierung für unterschiedliche Displays. Da ich einen 4k Monitor und das eingebaute hochauflösende Display normalerweise verwende, ist in manden Programmen wie MS-Teams das UI durch die Anwendung vergrößert. Das bedeutet wiederum, dass UI-Elemente auf dem Prompter unverhältnismäßig groß dargestellt werden, wodurch kaum Platz für den eigentlichen Inhalt bleibt. Das Problem liegt darin, dass MacOS standardmäßig alle Bildschirme gleich behandelt, was bei einem so niedrig auflösenden Display wie dem Prompter zu Darstellungsproblemen führt. Auf Windows kann ich hingegen einen Skalierungsfaktor pro Display einstellen, was die Darstellung deutlich verbessert. Allerdings funktioniert diese Skalierung nur imBereich von 100-500% - ich bekomme nicht mehr auf den kleinen Bildschirm, sondern eher weniger.

Der gescheiterte Spiegelungsversuch 🔄

Natürlich dachte ich, ich könnte einen meiner anderen Bildschirme (Notebook oder externes 4K-Display) einfach auf den Prompter spiegeln. Leider blieb der Prompter unter MacOS schwarz – die Auflösung des zu spiegelnden Hauptdisplays war einfach zu hoch.

Meine spezielle Lösung – HDMI-Dummy Stecker 🧩

Am Ende fand ich eine Lösung, die zwar ungewöhnlich ist, aber hervorragend funktioniert: Ich verwende HDMI-Dummy-Stecker, die einen HDMI-Monitor simulieren. So kann ich unter Windows und MacOS eine höhere Auflösung wie 1920 x 1080 Pixel (Full HD) auf dem dummy-Monitor einstellen und dann dieses virtuelle Display auf den Prompter spiegeln. Mit dieser Lösung erhalte ich eine skalierte Full-HD-Auflösung, die perfekt für die Darstellung von UI-Elementen ist und eine gute Qualität beim Teilen des Bildschirms ermöglicht.

Update 30.04.2025

Gestern konnte ich zwei weitere interessante erfahrungen machen.

Den Prompter nutze ich mittlerweile nur noch unter Windows, denn ich nutze eine Canon Spiegelreflex als Kamera. Die Treiber funktionieren nicht mehr mit Apple-Silicon und eine andere Kamera möchte ich momentan nicht einsetzen.

Schwarze Balken ohne HDMI-Dummy

Den HDMI-Dummy Stecker benötige ich unter Windows nicht unbedingt. Ich kann auch mein normales Display spiegel. Der Dummy-Stecker sorgt für weiteren Aufwand in meiner eh schon recht komplexen Verkabelung. Allerdings habe ich dann keine 16:9 Auflösung, die aber von meinen Slides erwartet wird. Dadurch ergeben sich beim Screensharing schwarze Balken

Elgato Camera Hub

Ein zweites Problem ist das helle Design meiner Slides. Das Display strahlt tatsächlich in die Kamera, wodurch ich blass rüber komme. Die Lösung ist, das Display zu dimmen. Allerdings hat der Elgato Camera Hub, mit dem man solche Einstellungen vornehmen kann, das Display nicht erkannt. Die unerwartete Lösung war, dass der Camera Hub das Display nur erkennt, wenn es nicht gespiegelt genutzt wird. Also erstmal die Displays wieder getrennt, dann das Display gedimmt, dann wieder das Hauptdisplay gespiegelt.

Table of Contents

DisplayLink statt DisplayPort – Ein unerwarteter Stolperstein 🔌
Die Enttäuschung über die Auflösung 🧱
MacOS vs. Windows – Ein Skalierungskrieg 🍏🪟
Der gescheiterte Spiegelungsversuch 🔄
Meine spezielle Lösung – HDMI-Dummy Stecker 🧩
Update 30.04.2025
- Schwarze Balken ohne HDMI-Dummy
- Elgato Camera Hub

iX: "Künstliche Intelligenz in der Softwarearchitektur praktisch einsetzen"

Mon, 9 Sep 2024 00:00:00 +0000

Künstliche Intelligenz in der Softwarearchitektur praktisch einsetzen

Künstliche Intelligenz macht Softwarearchitektur und kann Architektinnen und Architekten auf vielfältige Weise bei Entwurf, Prüfung oder Diagramm unterstützen.

Ein neuer Artikel für das Architektur-Sonderheft der iX.

Table of Contents

Künstliche Intelligenz in der Softwarearchitektur praktisch einsetzen

Softwarearchitektur: "KI wird unsere Fähigkeiten ergänzen, nicht ersetzen"

Sun, 22 Oct 2023 00:00:00 +0000

Software-Architektur und ChatGPT

Wie wird sich die Arbeit eines Software-Architekten mit KI verändern?

Ich probiere es aus und wage einen Blick in die Glaskugel…

(M)ein Interview auf heise.de

Table of Contents

Software-Architektur und ChatGPT

Software architecture: "AI will complement our skills, not replace them".

Sun, 22 Oct 2023 00:00:00 +0000

Software-Architecture and ChatGPT

How will the work of a software architect change with AI?

I try it out and dare a look into the crystal ball…

read my interview on isaqb.org…

Table of Contents

Software-Architecture and ChatGPT

Speed up your Podcast Editing with Generative AI (Developer Advocate Version)

Thu, 21 Sep 2023 00:00:00 +0000

Recording and editing a podcast is a lot of fun. There is something special talking to each other and exchanging ideas, have a laugh and producing an artifact that potentially a lot of people can listen to to get some value.

Thus said it is also a ton of work!

For producing the first season of J&J Talk AI I did nearly everything manually except the transcription where I used Whisper (I wrote an article about that).

For season 2 I wanted to automate as much as I could to reduce the time I have to spend with tedious tasks like writing a full transcription with nice formatting and speaker labels, creating a podcast description and social media posts. Furthermore I wanted to get rid of much of the postproduction stuff like silences, stutter or filler words.

So this blog post contains all the learnings which in sum reduced my editing/postproduction time to about 50% of what it was before - conservative estimation 🦄.

Recording Platform

For recording a podcast there is no way around an online recording solution now, because they record locally for every participant and upload the recording afterwards. This guarantees the best audio quality where nobody has a big hassle with their local setup except getting their microphone to work 😉.

Riverside.fm

For the first two seasons we used Riverside.fm as they offer a generous two hour recording limit for separated tracks.

They also offer some unique features like Magic-Clips creation.

Overall I liked the experience as the setup was easy. If you also want to edit inside a browser and get a transcript for free, Riverside.fm is your place to go.

The only downside I found and that might be specific to me was that the exported quality lacked. At least for my voice I had overly loud white noise and also the sound level was way to high in every recording. By cleaning it up my voice suffered which is a real bummer as the sound quality is excellent when I record locally 😕.

Streamyard

Streamyard — as the name implies — is designed for streaming. But it also has a recording feature which records locally.

Setup is fairly easy and straightforward making it an alternative to Riverside.fm if you do not need all the fancy features.

Also the audio quality seems to be a tick better in my opinion. And actually that is all I care about!

Descripts Squadcast

Disclaimer: I did not try Squadcast yet as I exhausted my free minutes with a transcription 🙃

Squadcast looks like Riverside.fm and Streamyard when it comes to features. The real gamechanger comes with the integration of Descript (See later in the article).

Having a recording solution where you do not have to import the recording into another tool looks like a no brainer to me.

Editing

Editing a podcast can be a daunting task. Not only do you have to cut silence, filler words, stuttering and mouth sounds.

You also have to normalize audio levels and apply some voice filters to make the voices sound professional.

Surely there are a lot of tools out there that can help with that, right? Right?

And yes there are a ton of tools out there that you can try for free to see what helps in your particular situation.

Note: Your recording setup may be different and thus your recording quality you start with different than mine. Take this into account when you read the reviews.

Auphonic

Auphonic looks extremely strong when you look at the features. Except from removing filler words it should be your one-shot solution to produce great audio.

Also the demos are impressive and I could not wait to try it out.

But unfortunately I could not make it work in my case. I experienced the following issues:

Noise was not removed completely
Normalization put too much gain on my voice
Loudness levels where not applied

What worked well:

Silence removal
The Auto-EQ.

Adobe Podcaster Enhancer

Adobe Podcaster offers a free audio enhancer where you can remove noise and echo from your audio, but not filler sounds and stuttering.

For me it did fail on:

Noise removal - Still noticable

But it did a great job enhancing the audio. Both voices felt rich after enhancing.

AI-Coustics

AI-coustics did a great job at removing noise. It was gone and the voices still sounded nice.

The only problem I noticed was that sometimes the volume levels dipped a little bit.

If you have heavy background noise I would probably use AI-coustics as in my opinion it did the best job with noise removal.

Audo-AI

Audo.AI did a similar good job with the audio quality like AI-coustics. But a little bit of background noise was noticable.

Descript

If I would create video or audio content every week I would definitely purchase Descript!

The editing is a completely different experience: You edit on the transcript! And then the audio adapts to that 🤯.

Removing specific filler words is a Search+Replace away. Getting rid of silence is also well done: You specify the gap width that should be shortened and to what it should be reduced.

Also the sound quality is great. No background noise hearable in my case.

Cleanvoice

For now I stuck with Cleanvoice because they have a credit based payment model. I purchased the credits and can use it any time I want.

The best thing about Cleanvoice is that it removes filler words, stuttering, background noise and silence automatically. Although you still have to edit a little bit, because automation makes mistakes 😉.

I had to invest about 15 minutes of additional editing per episode to get the same result as with Descript. Which is ok when you are only casually podcasting.

What Should I Use?

If you have the money for it I highly recommend Descript. The different approach to editing is intuitive and fast and the audio quality is top notch.

For now I use Cleanvoice as it is pay-what-you-use and the audio quality is as high as Descripts.

Transcription

A transcript of the recording is a nice way to reuse your content and also to make it accessible to everyone. For transcribing text I use Whisper (I wrote an article about that) locally. But you can also use any transcription service out there.

At least for the raw transcription this seems to be a solved problem. The medium model from Whisper produces nearly no errors. So I have to do only a few minutes of correction on each episode.

A raw transcription is nice if you want to feed it into a Large Language Model (LLM) like chatGPT. But it does not make for nice to read content because it misses two things:

Nice formatting
Speaker diarisation (Labels which speaker is speaking)

I was not able to try out some tools for the latter, but this Github repository looks promising.

Diarisation

So to get my speaker labels I did the diarisation manually and every time the speaker changes I added an empty line. The transcripts look like this:

Hello and welcome to J&J Talk AI. Today we are talking...

Hey there. Nice to be back gain!

The topic of this episode is...

Yeah, so...

Generating Speaker Labels Automatically with chatGPT

I then fed the diarised output to chatGPT with a prompt to add the speaker labels.

Note: This only works well if you have two speakers that naturally alternate.

The prompt looks like this:

Heyho, can you help me with a tedious task please.

So I have this long transcript of a podcast and I need you to add labels to a file. Here is an example:

JH: Yeah this is a podcast
JD: Welcome to it.

The labels are JH: and JD:

You can identify the blocks by an empty line. It starts with JD: and the next block with JH: and then it alternates between these two. Also do not label the blocks in any way please. Make sure the first block starts with JD: .

Here is the transcript:

This worked for me, although sometimes I got the modified transcript as a codesnippet 😋.

Generating Content

For generating further content I used chatGPT-3.5 which can handle the longer transcripts and works decently now.

The results where sometimes of mixed quality and I highly recommend to proofread them and give them a personal touch.

But the speedup at this stage for creating a podcast description, a LinkedIn post and a social messenger post, was fairly impressive. For the five episodes I needed about two hours of work to get the quality I wanted.

Last time this took me five hours which is an impressive speedup 🥳.

In the next section I will share my prompts and the reasoning behind it. I didn’t do much prompt engineering to be honest. Just some basic things I picked up in the last weeks. If someone wants to improve on them let me know what worked for you.

Podcast description

The prompt for the podcast description took some attempts. The model picked up on a lot of content in the transcript you do not want to be in a podcast description.

For example sponsor messages were included every time and also the opening lines. Especially annoying is the tendency to include a huge amount of emojis and add things that were not in the transcript at all.

So I made sure to add instructions not to add superfluous stuff and to be concise.

Heyho I want you to act as a Developer Advocate who is great at social media. The things you write should not be markety but should be engaging.

I want you to create a podcast description out of the text I provide. Keep the length short and to the point. Also do not use any emojis and direct quotations from the text I provide. Please take only content out of the text. No sponsor messages!

Here is the text:

Social Media: Short Message and LinkedIn

In social media I want some emojis so I made sure only some are there. Also again sponsor messages should not be included. But overall the results where great and I had to do only minimal editing.

Heyho I want you to act as a Developer Advocate who is great at social media. The things you write should not be markety but should be engaging.

I want you to create a Twitter post out of the text I provide. Do not overly use emojis and keep the tweet under 160 characters. Please take only content out of the text. No sponsor messages!

Here is the text:

LinkedIn looks nearly the same but without the character limit and the instruction to keep it brief:

Heyho I want you to act as a Developer Advocate who is great at social media. The things you write should not be markety but should be engaging.

I want you to create a LinkedIn Post out of the text I provide. Do not overly use emojis and keep it somewhat brief. Please take only content out of the text. No sponsor messages!

Here is the text:

Blogpost

For the blog post I had to put the diarised and speaker labeled transcript into a WYSIWYG-Editor which works, but is not optimal. There was one particular problem:

Bolden the speaker labels

Which is an easy Search+Replace in Markdown or AsciiDoc. But not in an WYSIWYG-Editor with no such feature.

Thus I tried to automate this using AskUI which worked decently in this case. Not faster, but less straining on my wrists 🦾.

Conclusion

My little experiments in automating a lot of things around my podcast were a lot of fun and brought a lot of insights on how to speed up things with AI/ML.

I managed to shave off a good amount of time for all the tasks.

Thus said, using Large Language Models like chatGPT still requires a lot of finesse and the results need editing. I would not try to fully automate everything if quality is important… Yet! 😇

Photo by Soundtrap on Unsplash.

Table of Contents

Recording Platform
Editing
Transcription
Conclusion

A Comprehensive DevRel Metrics Guide (Part 4): Company Stages and Reporting

Sun, 17 Sep 2023 00:00:00 +0000

Imagine you are working at an early stage startup and you are tasked with tracking meaningful metrics. And then imagine you are working at an enterprise company with the same task.

Would you track the same metrics?

I have been scratching my head over this question because it does not make sense to me that the metrics should be the same for both companies 🤔.

What Company Stages Are There?

I found an inspiring talk from Vera Tiago that resonated with me. There is also a written form of it, if that is more your thing 🥰.

In there she talks about North Star metrics and then comes to the topic of DevRel-Focus areas. Her Developer Relations focus areas are:

Awareness
Adoption
Education
Retention

And then she makes an interesting distinction between two areas you have to look at as a company:

Maturity of your product
Maturity of your community

So if you are an early stage startup you probably have an unmature product and a just forming community. Thus working towards retention may not be your highest priority as your product has to many kinks and your community is too small.

It should be better to work towards acquisition and adoption to get more users.

By doing this you get more feedback and exposure to achieve product market fit.

Figure 1. Vera Tiagos four pillars of DevRel and company stage (Source (a written form of it))

Evaluating and validating your company’s stage and your focus with management is extremely important as it again will determine the metrics you are prioritizing.

How to Do Reporting?

Many companies have a monthly All-Hands meeting. Some call it a Jour-Fix. Whatever you call it, entering your collected data into a nice presentation template gives you the possibility to always be ready to give a presentation.

I do not get into all the details in the presentation deck but focus on the things that matter now. Even when I track more than that as outlined in the previous blog post. There is a dedicated slide at the end where I link to the raw metrics if anyone is interested in them.

With the slide deck I am good to go to present 5-10 Minutes and give a concise update about how we are doing 🎉

Here is my template as a Google-Slide Deck.

Conclusion

And this marks the end of this series. We discussed why metrics are important, where to even start and my personal view on what metrics to track.

In this blog post I gave an introduction on what might be important and expected from DevRel at different company stages.

As always: Do not blindly follow advice but take it as a food for thought and an idea to test in your circumstance! I feel this is especially important in DevRel as no company is the same 🙃.

Photo by Andre Taissin on Unsplash.

Table of Contents

What Company Stages Are There?
How to Do Reporting?
Conclusion

A Comprehensive DevRel Metrics Guide (Part 3): A Framework to Get Started!

Fri, 16 Jun 2023 00:00:00 +0000

In part two of the series we discussed what DevRel north star metrics commonly get used across the industry. We also saw that it can be quite tricky to find the right metrics to measure because they are plenty, sometimes lag behind or the relation to your North Star is not direct but only delivered over time.

So what should we do?

I will answer this question in this article for people who are just starting out and looking for a way to have a solid foundation to build on. Because that is what I found myself in when I started my Developer Advocate journey 😊.

But also if you have something in place already. This article will help you make sense of metrics and give you inspiration.

The Solid Framework: Kim Maidas Keystone Framework

Just starting out with DevRel-Metrics? Look no further than Kim Maidas DevRel Metrics Keystone Framework. Over the course of her career leading in Developer Relations she says she found a way to holistically measure DevRel in a way the C-Suite understands. And I could not agree more!

Figure 1. Kim Maidas Keystone DevRel Metrics (Source: Kim Maidas article)

Her idea is to define one Keystone (North Star) as your guidance. Her recommended keystone is 1 signup/registration. Ideally it is your company’s North Star.

Once you have your keystone you can come up with a price tag for it. Yes, real money!

Then with a price tag you can attach a percentage of this keystone value to each metric in the following categories:

There is an order to it also. Reach metrics are at the top of the funnel and thus improving metrics from that category is not as valuable as further down the funnel. Engagement and finally DevRel Qualified Leads are worth so much more and you can add more value to each metric in those categories.

What you basically do is attaching a value tag on every metric and are thus able to calculate the value DevRel brings to the table 🥳.

I do not want to copy Kim Maidas article, so for the sake of brevity, I encourage you to read it and use her method to give every metric a meaning tied to company metrics.

There is also much more in her article that makes the read worthwile!

My Personal Additions

I personally found two additions helpful in showing impact on product/engineering:

Internal Impact
Direct Impact.

The first one captures the feedback you bring from the community into the company. The second one measures your direct impact you have by doing developer experience audits and creating content.

Internal Impact

In my daily work a lot of things I do are related to product development. Be it providing feedback for new features, betatesting new features, writing docs, gathering feedback from the community and relaying it back to development. The above areas do not cover them completely.

Luckily I found two articles that cover these areas well (See Sean Falconers - DevRel Metrics And Why They Matter) and The Core competencies of Developer Relations by Reto Meier. They talk about the developer relations cycle where they introduce Developer Feedback and Developer Sentiment that Developer Relations collects and brings into product development.

Figure 2. The Developer Relations ongoing interface cycle (Source: The Core competencies of Developer Relations by Reto Meier)

As you are acting as a middlehuman for these two, I call this internal impact as you affect your product through the feedback delivered.

What I like to measure here is the number of feedback and sentiment brought to the department in your company where it is best seated. If anything comes out of this feedback that is also noted down.

Direct Impact

As you have noticed, most metrics are loosely tied to company goals. But there are ways to demonstrate a direct impact. Things I found useful are the following:

Developer Experience Audits: Evaluating your product as a user would and providing detailed feedback and improvement suggestions to product management. You should also track what is finally implemented and if possible if any metric was impacted by the change (Less bug-tickets for example or specific user complaints decreasing).
Tracking your content’s impact: With sufficient tracking in place you can track if your company’s North Star metric is affected by your content like docs, blogs or videos. In fact this is what I do and I could demonstrate that videos on YouTube drive Sign Ups.

Conclusion Part 3

With a framework like the one from Kim Maida you can lay a solid foundation for all your metric needs in a structured way. It also makes reporting easier by directly tying individual metrics to your companies north star.

In the last part of the series we will dive into the wonderful world of company development stages and their individual needs from DevRel. Early stage startups are different than enterprise organizations. And there is a lot of space in between.

Thus we should shift our focus and the metrics we take into focus accordingly.

I will also share my template I use to report DevRel metrics every month.

Photo by Leonardo Vazquez: Source

Table of Contents

The Solid Framework: Kim Maidas Keystone Framework
My Personal Additions
- Internal Impact
- Direct Impact
Conclusion Part 3

A Comprehensive DevRel Metrics Guide (Part 2): What DevRel Metrics should I track?

Wed, 7 Jun 2023 00:00:00 +0000

Now that we got the Why? out of the way in part 1. Let’s face the difficult challenge on what DevRel Metrics we should collect in the first place.

Of course I will stand on the shoulders of giants here again as a lot of smart DevRel-practitioners have already written about this.

The goal of this post is to get to a common understanding what others usually track. I also want to give you my opinion on metrics as I think there is so much confusion about metrics. I believe that a pragmatic approach is reasonable to be practical for each individual situation.

We will discuss the following things:

DevRel North Star metrics: Why they are useful but not sufficient
Common metrics that are collected in the industry
My critique and opinion about this

DevRel North Star Metrics

Swyx claims nearly all companies settle on one specific metric: Monthly Active Developers (Source: Measuring DevRel by swyx)

Also popular:

Registered Developer Accounts (Source: Slashdata Report 2020)
Developer Satisfaction score (Source: Slashdata Report 2020)
Time To Hello World (TTHW) (Source: Sean Falconers - DevRel Metrics And Why They Matter)
Time to First WOW! Exclamation (TTFWE) (My own invention: The first time a user experiences and realizes the value of your product. Sorry had to sneak that in here 😋)
Number of signups / registrations (Source: Kim Maidas Keystone Framework)
…

Also, have a look at DevRel-KPIs.com for more inspiration.

Common Metrics in the Industry

So this may be useful when you have to report one or two numbers to management, but not sufficient of what DevRel is actually doing in their day-to-day work.

Many more metrics have been collected and I will just link them here for you to explore and get an idea.

I really like the supporting DevRel Metrics swyx compiled for his North Star metric Monthly Active Developers.

Figure 1. Metrics that feed into Monthly Active Developers North Star Metric.(Source: Measuring DevRel by swyx)

From Kim Maidas Keystone Framework:

Also again DevRel-KPIs.com is a great resource to get you going.

Are There Bad Metrics

I would say It depends 😋

Usually you do not want to be measured with a marketing metric. We are dealing with relations here, remember? But if we produce content for example that is for creating awareness or inspiration. What metrics can we actually collect to measure its success? In my opinion this would be something like views or likes or Github-stars.

So I suggest the following: Be pragmatic with what you track. There is no harm in collecting a marketing metric if it fits your current situation. If management cares about these sometimes so called Vanity Metrics, even better. Easy to collect and report on.

But do not get caught up in them! An audience is not a community and you want to foster real relationships 😊

My Critique and Opinion About This

It always felt wrong as a software developer to reduce a complex topic into a single number. It feels even more so with DevRel. I get that management would like to have a single number to gauge how DevRel is doing. But DevRel performs a cross-functional function in a company. The metrics are influenced by a lot of departments and also ultimately by the state your product is in.

A metric like Monthly Active Developers is a great metric if the management trusts that you influence it positively. The problem is, that it is usually influenced by a lot of departments like product, support, technical writing, marketing and so forth. If your product has sharp edges you can not work around even with the best onboarding and with the best feedback for engineering you can possibly provide: Good luck with improving your TTHW!

The only thing you can then do is to try and improve the supporting metrics as swyx suggests. But even this will not get you far in my opinion because you are only applying bandaids.

Also tieing your activities to a North Star metric may sometimes be hard as it can lag significantly behind. Not every relationship or piece of content has an impact immediately. Often it is a compounding effect of positive encounters that tips the scale. Relationships are built over time!

Conclusion Part 2

In this post we discussed popular DevRel-North Star metrics like Monthly Active Developers used in the industry. They are useful when reporting to management, but not sufficient to measure the complex day-to-day work or specific project/campaigns DevRel is focusing on in a specific company.

We gave a lot of pointers on what you can also collect with the general recommmendation to be pragmatic and, if possible, to focus on metrics that cover relationships.

In the next part of this series we will cover Kim Maidas Keystone Framework. It is a great framework if you are just starting out! I use it with a few extensions. It is useful in my current situation and it includes the Relations part of a DevRel-Practitioner!

Photo by Igor Mashkov: Source

Table of Contents

DevRel North Star Metrics
Common Metrics in the Industry
- Are There Bad Metrics
My Critique and Opinion About This
Conclusion Part 2

A Comprehensive DevRel Metrics Guide (Part 1): Why Track Metrics Anyway?

Thu, 1 Jun 2023 00:00:00 +0000

Metrics are the bane of existence for DevRel folks out there. At least in my perception. There seems to be a state of constant confusion and vague advice. I even watched a panel discussion about metrics once, where everybody seemed to avoid giving exact recommendations on how to tackle them.

So I embarked on a mission to get this sorted out for myself only to discover, that it is complicated enough to spend hours on end on it :-D

This post-series brings together everything I found out about DevRel metrics. I surfaced a ton by doing extensive research over 20+ hours and applying it directly at my current company.

At the end of the series you will have a solid understanding of:

Why you should even track anything?
What should you even track?
How to make a strong case for DevRel with your metrics?
How to do reporting?

Start From The Top

The age-old question Why should I measure? and you always get the same Drucker quote… Do not worry: Not here!

For me tracking metrics helps me see clearer in terms of direction. As my manager put it: “You can run pretty fast in the wrong direction! So you better NOT do that!”

What does your Company Care about?

Let us face the harsh truth first: "Nearly all companies care about is money!". For me this is clear and it should be clear to you. Money keeps the lights on and your paycheck delivered to your bank account. This is not just me who thinks like this but a lot of DevRel folks have written about this already.

Often there is one key metric that is used to communicate the health of a company: The North Star or Keystone.

Also as a side note: Just because your company only really cares about money, it is not the thing you aim for in your job directly as you will see later!

What Is a North Star/Keystone Metric?

I stand on the shoulders of giants here as I like the following definitions:

Tera Viago says that a North Star Metric is your company metric. And “In the end it is all about money and customer satisfaction”! (Source: YouTube-Video)

Sean Falconer defines it as "A North Star metric is a single measurement that is predictive to your company’s or product’s long-term success." (Source: Blog Post)

Examples from companies:

Spotify: Time Spent listening
airbnb: Booked nights
LinkedIn: Monthly Active Users (MAU)

What is your Company North Star?

So how does this translate to metrics for your company? It may be one of those:

Annual recurring revenue (ARR)
Number of Sign Ups
Number of Paying customers
…

To everyone I have talked to by now they know their companies North Star as it is communicated often through all channels.

Why do I need a Company North Star for DevRel Metrics?

If you look for metrics to measure you should always strive to find the metrics that are tied directly to company goals in some way.

But there is a catch and something I had to wrap my head around. DevRel is so far away from a hard North Star metric as it could be.

Kurt Kemple has a nice chain-of-metrics graphic which illustrates this dilemma.

Figure 1. Chain of trusted metrics (Source: Kurt Kemples Developer Advocates Guide to Metrics and Reporting). You see that everything DevRel does is at the end of the chain. And the farther away you get from your North Star, the harder it gets to tie them to a hard and trusted metric like Annual Recurring Revenue (ARR).

Why should you care about DevRel-Metrics?

All this DevRel-Metrics talk makes me tired. Why should I care about metrics, when all I want to do is help my developer community?

Well, there are two things to consider:

If you can not communicate your value to upper management by showing how you impact their metrics… Your value might be underestimated. And guess who gets laid off more likely? Yes, somebody not helping the company succeed.
There are so many different things you can do to improve the life of your development community. Blog posts, tutorials in written or video form, engaging directly by giving talks. Providing great docs. But what should you do? If you do not track what has an impact on your business you just do not know. For example at my current company we are testing a lot of stuff that we think will help our community and our company. And we measure it as good as we can. Some things turned out useless already. Some others were surprisingly helpful. Without a metric, we would not know what to focus on.

What Are We Going to Do?

The thing I realized is that determining what to measure and how to tie it to a meaningful company metric is the reason I struggle to wrap my head around DevRel-Metrics: They ARE hard to make sense of and I have to find the ones that are important for my company!

What adds to that is that they are diverse and also distributed across different areas.

So over the next few blog posts we will look at:

A lot of metrics suggested by knowledgeable DevRel practitioners and thinkers.
Then we will discuss Kim Maidas Keystone Framework. Where she explains what metrics she tracks and how she makes them quantifiable, so they can be communicated in cold hard numbers.
After that we will dive into the different development stages companies can be in and what it means for choosing the correct metrics. Because what is important to track for a startup is completely different for an enterprise company.
In the last part I will share my own experiences and opinion in applying the Keystone Framework and extending it to my needs.

Conclusion Part 1

Tying your metrics to your companies North Star in a meaningful way is important but difficult. DevRel-Metrics are usually far away from cold hard numbers relating to a North Star.

But measuring and communicating your value is important to not get laid off and to get an idea what is actually working.

So in the next part we will look at a plethora of metrics other more influential DevRel practitioners compiled.

Cover art image by Daniel Torobekov: Source

Table of Contents

Start From The Top
What does your Company Care about?
What Is a North Star/Keystone Metric?
What is your Company North Star?
Why do I need a Company North Star for DevRel Metrics?
Why should you care about DevRel-Metrics?
What Are We Going to Do?
Conclusion Part 1

How to Create Subtitle-Files (srt) with WhisperAI

Mon, 20 Mar 2023 00:00:00 +0000

For my tutorial videos I want to provide high-quality subtitles. But I did not want to write them myself as this is a tedious task.

Luckily there is WhisperAI that can help me, or so it promises 😂 Time to give it a shot for my current project.

Install WhisperAI

I followed their installation guide on their GitHub-Repository side. It is a Python tool so the first step I did was setting up a virtual-environment (my current installed version is 3.9.6 on macOS. Here are all the commands I ran:

## I installed python with brew as far as I remember ;-)
## Initialize and activate the virtualenv
python3 -m venv venv
source venv/bin/activate

## Install latest WhisperAI from Github
pip install git+https://github.com/openai/whisper.git

## Install ffmpeg
brew install ffmpeg

Create Util-Script for Easier Handling

With that set I created a little script based on this Gist. It was for an older version of WhisperAI so I had to implement some changes. Save it as createSrt.py or whatever name you like 😋:

import sys

import whisper
from whisper.utils import get_writer


def run(input_path: str, output_name: str = "", output_directory: str = "./") -> None:
    model = whisper.load_model("medium")
    result = model.transcribe(input_path)

    writer = get_writer("srt", str(output_directory))
    writer(result, output_name)

def main() -> None:
    if len(sys.argv) != 4:
        print(
            "Error: Invalid number of arguments.\n"
            "Usage: python createSrt.py <input-path> <output-name> <output-directory>\n"
            "Example: python createSrt.py transcribed.srt ./transcribed"
        )
        sys.exit(1)

    run(input_path=sys.argv[1], output_name=sys.argv[2], output_directory=sys.argv[3])


if __name__ == "__main__":
    main()

Usage of Util-Script

You can call it like this and it can handle .wav and also .mp4. So you do not even have to export your videos in another format to use it:

python createSrt.py <path to your mp4/wav file> <name of the srt file> <path to where to save the srt file>

Adjustments

If you want to use another model instead of medium you have to change the following line and replace medium with a model documented here:

model = whisper.load_model("medium")

If you want to change the output format you can use one of the following instead of srt: vtt, tsv, json. Change it in the following line:

writer = get_writer("srt", str(output_directory))

Happy transcribing 🦄

Let Grails fly in the cloud

Mon, 13 Feb 2023 00:00:00 +0000

This week I wanted to load test a grails application under real conditions. So I needed a simple way to deploy a grails application to a real server (not my notebook).

So, I asked my followers on twitter and mastodon, what cloud service I should use.

I quickly got a response from Patrick Baumgartner to use fly.io as a service.

Fly IO has some free tier. See - https://t.co/iJP12wPWSe

I haven't used it yet because I run my dockerized apps on my NAS @Synology
— Patrick Baumgartner (@patbaumgartner) February 8, 2023

A quick check showed me that fly.io seems to be really a simple service with a good free tier.

Let’s see how you can deploy your grails app to fly.io …

Setup a Grails Starter

First, go to https://start.grails.org/ and download a starter app. Since I didn’t modify the defaults, a simple

curl -O https://start.grails.org/myapp.zip
unzip myapp.zip

also does the trick. You can now create some simple domain objects as described in the quick start guide "https://guides.grails.org/creating-your-first-grails-app/guide/index.html[Creating your first Grails Application]" - but you don’t have to. The basic application template will be enough to test the deployment to fly.io .

Now, modify the app to create a fat-jar file instead of a .war . Remove the reference to the war plugin from the build.gradle config (line 19):

//apply plugin:"war"

In order to avoid having to set up a database, I also modified the production configuration to use an in-memory database. In grails-app/conf/application.yml, I copied the development datasource over to the production one (line 122):

grails-app/conf/application.yml

production:
    dataSource:
        dbCreate: create-drop
        url: jdbc:h2:mem:devDb;LOCK_TIMEOUT=10000;DB_CLOSE_ON_EXIT=FALSE

… and deploy to fly.io

Next, create a simple Dockerfile with the following content:

Dockerfile

FROM openjdk:14-ea-alpine3.10

EXPOSE 8080

WORKDIR /app
COPY *.jar application.jar

CMD ["java","-Djava.security.egd=file:/dev/./urandom","-jar","/app/application.jar"]

yes, this is not perfect. It is just a quick hack.

Now, everything is prepared for the last few steps. To test your grails app, execute the following steps on the command line:

./grailsw package
cp build/libs/myapp-0.1.jar .
docker build --tag="grails-sample/complete:0.1" .
docker run -p 8080:8080 grails-sample/complete:0.1

This will test-run your app locally as docker image.

To deploy it to fly.io, execute

./grailsw package
cp build/libs/myapp-0.1.jar .
fly launch
fly apps list

Now, this is the part where you have to leave the free tier, but it is still cheap. If you go to your monitoring dashboard at fly.io, you will notice that your app crashed because of low memory (256MB). So, scale it up to 1GB (don’t have to redeploy) and it will run flawless :-)

Hope this little guide will help you with your own deployment.

for feedback and discussion: Twitter, Mastodon

Table of Contents

Setup a Grails Starter
… and deploy to fly.io

Nerd-Spielzeug: WiFi AP

Thu, 26 Jan 2023 00:00:00 +0000

Das letzte Mal habe ich von den Features von Zümi erzählt. Dieses Mal möchte ich die Umsetzung des ersten Features beschreiben.

Da ich mit dem Aufsetzen des WiFi Access Points die meisten Probleme hatte, beginne ich auch damit.

Das Ziel ist es den Raspberry so aufzusetzen, dass er einen Access Point bereitstellt, über den man auf einen Webserver und somit webbasierte Software auf dem Raspberry Pi zugreifen kann. Als Bonus soll sich der Raspberry Pi auch über ein weiteres WiFi Netz mit dem Internet verbinden und diese Verbindung durchreichen. In diesem Fall spricht man auch von Bridging.

Warum ist das so schwierig? Den Raspberry Pi betreibe ich gerne headless (ohne Monitor) und verbinde mich per SSH über WiFi mit ihm. Wenn ich nun mit der WiFi-Konfiguration rumspiele und etwas schiefläuft, dann ist die Wahrscheinlichkeit hoch, dass ich von Vorne anfangen muss, weil ich mich ausgesperrt habe 😒.

Eine zweite Herausforderung ist die Tatsache, dass ein WiFi-Modul zwei Verbindungen herstellen muss. Aber dieses Problem haben schon andere schlaue Köpfe gelöst.

Lösung

Auf der Suche im Internet nach einer Lösung bin ich auf viele Tutorials gestossen. So beschreibt z.B. die Raspberry Pi Dokumentation direkt das Setup des Wireless Access Points. Hier wird die WiFi-Verbindung jedoch auf den Ethernet-Port geroutet. Auch das manuelle Setup sagt mir nicht ganz zu, da die Erfahrungen mit solchen Tutorials, gepaart mit meinem Know-How, nicht immer positiv waren.

Die Lösung habe ich dann auf https://raspap.com/ gefunden.

"The easiest, full-featured wireless router setup for Debian-based devices. Period."

Eine Open Source WiFi Access Point Lösung mit Web-Interface 😍.

Das initiale installieren geht über ein geführtes Setup ganz leicht. Beim Konfigurieren sperrt man sich aber ganz leicht aus. Deshalb hier meine Tipps:

beim Aufsetzen des Raspi, nach dem ersten Booten über sudo raspi-config das WiFi-Passwort neu setzen. Aus Sicherheitsgründen wurde es mit einem Token ersetzt, welcher zu Problemen mit dem RaspAP Frontend führt.
befolge die Anleitung auf AP-STA peinlich genau
Beim Start des Setup die erste Frage nach dem Installationsverzeichnis /var/www/html verneinen, um als Verzeichnis /var/www/html/raspap anzugeben. Dadurch ist RaspAP dann unter http://server/raspap erreichbar und der dafür installiere Webserver kann leicht noch für eigene Websites verwendet werden.
Im RaspAP Frontend unter dem Punkt "Wireless Client" die bestehende Verbindung erneut herstellen.
Der "WiFi client AP mode"-Button ist weiter ausgegraut? Unter dem Reiter "Logging" das Logging kurz aktivieren und speichern. Danach sollte der Button funktionieren.

Table of Contents

Lösung

Docs-as-Code Gedanken

Wed, 11 Jan 2023 00:00:00 +0000

docusaurus und mdx
Antora syntax
Antora repositories
reicht SSG aus?

Nerd-Spielzeug: Zümi

Tue, 20 Dec 2022 00:00:00 +0000

Die letzten Jahre habe ich mich immer wieder für verschiedene nerdige Themen wie 3D-Druck, Raspberry Pi, Arduino und Elektronik interessiert. Aber ich habe mir nie die Zeit genommen was mit diesem Wissen umzusetzen.

Doch jetzt ist es an der Zeit. Inspiriert von Zümi, einem kleinen Roboter-Auto mit Raspberry Pi unter der Haube, habe ich angefangen mein eigenes Nerd-Spielzeug umzusetzen.

Aber fangen wir vorne an.

Was ist Zümi?

Zümi ist ein cleveres Lernspielzeug der Firma Robolink. Anscheinend wurde er mittlerweile auf Zumi umgetauft, das hindert mich aber nicht daran, ihn weiterhin Zümi zu nennen, denn ich habe meinen durch die damalige Kickstarter Kampagne als "Zümi" bekommen :-). Den besten Überblick über die Features von Zümi gibt es natürlich auf der Produktwebsite. Lasst mich die Features aber nochmal aus der Sicht eines Nerds beschreiben.

Was kann Zümi?

Zümi ist autonom. Er verfügt über einen Akku mit Ladelogik, zwei Motoren, ein kleines, monochromes OLED-Display, eine Kamera und einen Raspberry Pi.

Der Raspberry Pi braucht seine Zeit zum Booten und kann sich nicht um die Ladelogik kümmern. Deshalb wurde er ganz clever um einen Arduino ergänzt, der die Ladelogik übernimmt und das Display ansteuert. Dadurch kann er beim Laden den Zustand am Display anzeigen und bringt beim Einschalten zwei animierte Augen auf das Display, die anzeigen, dass der Raspberry aufwacht. So wird die Zeit des Bootvorgangs clever überbrückt.

Das eingebaute Display ist sehr klein und eignet sich somit nicht sehr gut für die Programmierung. Deshalb haben sich die Entwickler ein weiteres cleveres Detail einfallen lassen. Zümi macht nach dem Booten einen WiFi-Access-Point auf. Auf dem Display wird der Name des WiFi-Netzwerks angezeigt und Zümi reagiert sogar auf eine Verbindung mit der Ausgabe der URL, über die man nach dem Verbindungsaufbau das Dashboard erreicht.

Über das Dashboard kann Zümi noch in das standard WLAN-Netz integriert werden, so daß eine WiFi-Bridge ins Internet aufgebaut wird.

Über das Dashboard stehen mehrere Jupyter Notebooks mit Tutorials zur Verfügung. Diese Tutorials zeigen, wie Zümi gesteuert wird. Highlights sind eine Gesichtserkennung und eine QR-Code-Erkennung. Beide sind über openCV realisiert.

Zur genaueren Steuerung der Motoren verfügt Zümi noch über einen Beschleunigungs- und einen Gyro-Sensor.

Alles in allem eine sehr runde Geschichte, wäre da nicht der Raspberry Pi Zero der ersten Generation. Dieser verfügt über nur einen Core und fühlt sich dadurch langsam an. Das System blockiert öfters und vermittelt das Gefühl, dass es nicht für größere Aufgaben geeignet ist.

Das von Robolink bereitgestellte SD-Card-Image ist etwas älter und läuft somit nicht auf einem Pi Zero 2. Da unklar ist, was und wie alles auf dem Image installiert ist, ist ein Upgrade schwierig. Robolink selbst scheint kein Interesse an einem Upgrade zu haben.

Somit habe ich mir zum Ziel gesetzt mein eigenes Nerd-Spielzeug in ähnlicher Art und Weise aufzusetzen.

In den nächsten Blog-Posts werde ich Schritt für Schritt erklären, wie ich dabei vorgehen. Lasst Euch überraschen!

Table of Contents

Was ist Zümi?
Was kann Zümi?

Nerd-Toy: Zümi

Tue, 20 Dec 2022 00:00:00 +0000

For the last few years, I’ve been interested in various nerdy topics like 3D printing, Raspberry Pi, Arduino and electronics. But I have never taken the time to do anything with this knowledge.

But now it’s time. Inspired by Zümi, a small robot car with Raspberry Pi under the bonnet, I have started to implement my own nerd toy.

But let’s start at the beginning.

What is Zümi?

Zümi is a clever educational toy from the company Robolink. Apparently it has been renamed Zumi in the meantime, but that doesn’t stop me from still calling it Zümi, because I got mine through the Kickstarter campaign at the time as "Zümi" :-). Of course, the best overview of Zümi’s features can be found on the product website. But let me describe the features again from a nerd’s point of view.

What can Zümi do?

Zümi is autonomous. It has a battery with charging logic, two motors, a small monochrome OLED display, a camera and a Raspberry Pi.

The Raspberry Pi takes its time to boot up and cannot take care of the charging logic. Therefore, it was cleverly supplemented with an Arduino, which takes over the charging logic and controls the display. This allows it to show the status on the display when charging and brings two animated eyes on the display when switching on, indicating that the Raspberry is waking up. This cleverly bridges the time of the boot process.

The built-in display is very small and therefore not very suitable for programming. Therefore, the developers have come up with another clever detail. After booting, Zümi opens a WiFi access point. The name of the WiFi network is shown on the display and Zümi even responds to a connection by outputting the URL that is used to reach the dashboard after the connection is established.

Via the dashboard, Zümi can also be integrated into the standard WLAN network, so that a WiFi bridge to the Internet is established.

Several Jupyter Notebooks with tutorials are available via the dashboard. These tutorials show how Zümi is controlled. Highlights are a face recognition and a QR code recognition. Both are realised via openCV.

For more precise control of the motors, Zümi also has an acceleration and a gyro sensor.

All in all, a very well-rounded story, were it not for the first-generation Raspberry Pi Zero. This has only one core and feels slow as a result. The system locks up frequently and gives the feeling that it is not suitable for larger tasks.

The SD card image provided by Robolink is somewhat older and therefore does not run on a Pi Zero 2. Since it is unclear what and how everything is installed on the image, upgrading is difficult. Robolink itself seems to have no interest in an upgrade.

So I have set myself the goal of setting up my own nerd toy in a similar way.

In the next blog posts I will explain step by step how I proceed. Let me surprise you!

Table of Contents

What is Zümi?
What can Zümi do?

Stoizismus - Praktische Philosophie für den IT-Alltag

Sun, 4 Sep 2022 00:00:00 +0000

Dieser Post basiert auf meinem Vortrag Stoizismus - Eine Praktische Philosophie für den IT-Alltag. Das Video dazu ist auf meiner Talkseite verlinkt.

Philosophie für IT?

Warum Philosophie auf einem Tech-Blog? Mag sich die Eine oder der Andere Fragen. Für mich ist der Umgang mit Menschen manchmal schwierig, da ich eine eher kurze Zündschnur besitze. Technik ist einfach und logisch im Vergleich zum Verhalten von so manchen Kolleg:innen. Gerade in der heutigen Arbeitswelt lässt sich Kommunikation nicht mehr vermeiden. Also musste ich für mich einen Weg finden, professionell mit Herausforderungen in diesem Bereich umzugehen.

Ich weiß nicht mehr wo es war, aber so um 2018 bin ich über den Stoizismus gestolpert und habe mich seitdem immer weiter damit beschäftigt. Inzwischen bin ich der festen Überzeugung, dass diese Philosophie für jede:n ein Gewinn ist, der:die sich auch nur damit auseinandersetzt. Deswegen erzähle ich jedem davon, der es nicht hören will ;-)

Stoizismus - Praktische Philosophie

Philosophie hat in vielen Köpfen etwas mit weltfremden Diskussionen zu tun, die keinen praktischen Nutzen haben im Alltag.

Im Gegensatz dazu stehen die Praktischen Philosophien, zu denen auch der Stoizismus gehört. Sie beschäftigen sich explizit mit dem Alltag, genauer gesagt mit zwischenmenschlichen Beziehungen. Stoizismus im Speziellen stellt sich die folgende Frage:

Wie lebe ich mein Leben so, dass ich überglücklich bin und es reibungslos verläuft?

In der stoischen Philosophie geht es darum ein Leben in Einklang mit den stoischen Tugenden zu leben und der:die perfekte Stoiker:in zu werden, der:die unter anderem sein:ihr Urteilsvermögen ungetrübt von Emotionen einsetzen kann. Da wir Menschen sind und Emotionen zu unserer Natur gehören ist dieses Ideal natürlich nicht erreichbar. Dazu aber später mehr.

Aus diesem Streben erwächst dann das Glück!

Gehen wir zum nächsten Abschnitt, in dem ich die Kernaussagen des Stoizismus zusammenfasse.

Hier bitte nicht vergessen, dass ich ein Schüler des Stoizismus bin und es zusätzlich viele verschiedene Interpretierungen in der Literatur gibt!

Kernideen

Eine wunderschöne grafische Zusammenfassung der stoischen Kernideen ist das stoische Glücksdreieck. Weit oben steht Verantwortung zu übernehmen für sein Tun und seine Reaktionen. Das ist aber erst möglich, wenn die beiden Fundamente Leben in Aretè und Fokus auf das Kontrollierbare gemeistert wurden. In der Mitte steht das höchste Ziel: Eudaimonia. Ein zusammengesetztes Wort mit der Bedeutung, mit seinem inneren Selbst (Daimon) im Reinen zu sein (Eu).

Leben in Areté

In dieser Ecke des Dreiecks geht es um Tugenden und darum nach diesen zu leben. Das bedeutet in unserem Handeln diese Tugenden auszudrücken.

Weißheit: Im Sinne von guter Urteilsfähigkeit, die überlegt ist und nicht gedankenlos
Gerechtigkeit: Hier geht es um die Beziehung zu unseren Mitmenschen, in denen integer und fair gehandelt werden soll
Mut: In einer Situation richtig zu handeln. Entgegen jedweden Widerstands (auch inneren)
Selbst-Disziplin: Im Stoizismus vor allem die angemessene Reaktion auf Emotionen und starkes Begehren in jeder Hinsicht

Noch hinzuzufügen ist, dass für Stoiker:innen alle Tugenden wichtig sind. Wird eine nicht gelebt, dann wird es schwierig Eudaimonia zu erreichen. Trotzdem haben alle Stoiker:innen in ihrem Leben festgestellt, dass sie Probleme haben immer nach den Tugenden zu handeln.

Seneca ist ein sehr berühmtes Beispiel. Als einer der reichsten Männer seiner Zeit wurde ihm oft Heuchlerei vorgeworfen, da er im Überfluss lebte. Er pflegte ein abendliches Journal in dem er offen über alle Vorkommnisse das Tages schrieb. Er war sich seinen Fehlern bewusst. Wichtig ist nur, sein Bestes zu geben!

Fokus auf das Kontrollierbare

Umgangsprachlich wird der Begriff stoisch mit Gefühlslosigkeit gleichgesetzt. Das kommt daher, dass Stoiker:innen ihren Fokus auf das Kontrollierbare legen. Dazu unterteilen sie Dinge, die Passieren, in vier Kategorien:

Kein Einfluss: Fast alle externen Einflüsse
Teilweiser Einfluss: Zum Beispiel die Reaktionen auf unser Verhalten oder auch Gesundheit
Indifferent aber bevorzugt: Reich oder arm zu sein sollte keinen Einfluss darauf haben, ob wir ein stoisches Leben führen. Reich sein ist aber definitiv angenehmer ;-)
Hoher Einfluss: Die wichtigste Kategorie, aber auch die kleinste. Unser Urteilsvermögen und Handeln

Nur die vierte Kategorie können wir wirklich kontrollieren. Das heißt, sich zum Beispiel über das Wetter zu beschweren ist nicht sinnvoll, da es nur akzeptiert werden kann. Die Kunst ist es, in jeder Situation in Einklang mit den stoischen Tugenden zu reagieren.

Verantwortung übernehmen

Ohne die beiden Fundamente kann keine Verantwortung übernommen werden. Was wirklich in unserer Verantwortung liegt ist, wie wir auf ein Ereignis reagieren. So ist es dem Wetter (um bei dem Beispiel zu bleiben) ziemlich egal, ob wir uns darüber freuen, indifferent oder genervt sind. Es liegt also in unserer Verantwortung zu entscheiden, wie wir uns fühlen.

Das ist einfach geschrieben, aber sehr schwierig umzusetzen! Deswegen sehen wir uns in den nächsten Abschnitten an, welchen praktischen Nutzen uns das bringt und welche stoischen Übungen es gibt, mit denen wir das stoische Glücksdreieck verinnerlichen können.

Praktischer Nutzen

Für mich der größte praktische Nutzen war die Erkenntnis, dass wir einen hohen Einfluss auf unsere Reaktionen auf externe Ereignisse haben. Insbesondere in den normalen Reaktionen in Social Media sehen wir genau das Gegenteil. Hier ist die Empörungskultur am Werk. Auf jeden Tweet wird sofort scharf in den Kommentaren reagiert, bis hin zu Beleidigungen. Sehr oft unberechtigt, aber auch ohne die Einsicht, dass das Medium an sich sehr beschränkt ist in seiner Ausdrucksfähigkeit.

Figure 1. Auf einen Stimulus wird normalerweise ohne nachzudenken instinktiv reagiert.

Stattdessen können wir uns einen Effekt zunutze machen, der uns wieder die Kontrolle zurückgibt. Es gibt eine kurze Zeitspanne zwischen dem Ereignis und unserer spontanen Reaktion darauf. Mir persönlich ist er erst aufgefallen, nachdem ich davon gewusst habe. Ich rate daher dazu, sich selbst genauer zu beobachten. Die Chancen stehen sehr gut, dass es bei allen Menschen so ist ;-). Greifen wir genau zu diesem Zeitpunkt ein, können wir rational überlegen, was die passende Reaktion auf ein Ereignis ist. Dadurch gewinnen wir die Kontrolle zurück und lösen uns davon, nur emotionsgesteuert zu handeln.

Figure 2. Die stoische Vorgehensweise auf einen Stimulus zuerst zurückzutreten und überlegt zu reagieren.

Stoische Übungen

Um in jeder Situation angemessen zu reagieren, ist es nicht genug über das theoretische Wissen zu verfügen. Das wussten schon die antiken Stoiker:innen. Deswegen gibt es eine große Palette an stoischen Übungen, die uns mental trainieren, angemessen zu reagieren.

Ich werde zwei meiner Lieblingsübungen vorstellen, da sie mir persönlich sehr geholfen haben im Alltag.

Gelassenheit kaufen

Beim Essen habe ich das Talent zu kleckern. Diese Übung hat mir geholfen, die negative Stimme in meinem Kopf nach einem solchen Vorfall auszuschalten und stattdessen zu üben, mit Unfällen umzugehen. Bis dahin habe ich nach jeder Kleckerei eine Weile darüber sinniert, wie dumm das doch war. Inzwischen kann ich über das meiste Lachen oder es ist mir einfach egal. Deswegen kaufe ich mir mit dieser Übung Gelassenheit. Sie geht so:

Sobald ein kleines Missgeschick geschieht: Die Gelegenheit nutzen und sich selbst beobachten. Die Gefühle akzeptieren und dann zu sich selbst sagen während des Aufräumens: "Für diese Kleinigkeit kaufe ich mir Gelassenheit!" Die Effekte bei mir waren eine größere Gelassenheit im Alltag. Kleine Missgeschicke hängen mir inzwischen gar nicht mehr nach, was mich zufriedener mit mir selbst gemacht hat.

Premeditatio Malorum

Kennt ihr diese Menschen, die alles exakt bis auf die letzte Minute durchplanen, wenn sie auf Reisen gehen. Nur um dann festzustellen, dass sie etwas Wichtiges wie Zahnpasta vergessen haben? Genau so jemand war ich auch. Jetzt liegt es aber in der Natur der Sache, bei einer Reise irgendetwas zu vergessen. Das Meiste ist aber ersetzbar. Drogerieartikel gibt es überall und auch größere Dinge wie Netzteile für Elektronik.

Die Übung Premeditatio Malorum hilft bei der mentalen Vorbereitung auf Fehlschläge. Es macht einen großen Unterschied, ob über mögliche Schwierigkeiten nachgedacht wurde oder nicht. Dadurch kann in der Situation rationaler reagiert werden, selbst wenn sie im Kopf noch nicht durchgespielt wurde. Alleine der Akt darüber nachzudenken hilft. Deswegen rate ich dazu, nicht vollständig alles zu durchdenken, sondern nur ein paar Eventualitäten.

Inzwischen bin ich bei Reisen dadurch sehr entspannt, sogar als ich dann wirklich einmal meine Zahnbürste und Zahnpasta vergessen hatte.

Weiterführende Gedanken und Leseempfehlungen

Es gibt noch viel mehr zu entdecken im Stoizismus als das, was ich hier beschrieben habe. Jedes mal, wenn ich wieder ein Buch über Stoizismus in die Hand nehme und es lese, kommen neue Einsichten dazu. Ich kann nur empfehlen mit dem einsteigerfreundlichen Buch The Little Book of Stoicism von Jonas Salzgeber loszulegen, da es sehr konzentriert alle wichtigen Kernaussagen des Stoizismus verständlich rüberbringt.

Leseempfehlungen

The Little Book of Stoicism - Jonas Salzgeber
The Practicing Stoic - Farnsworth
How to Think Like a Roman Emperor - Donald Robertson
Webseite von Nils und Jonas Salzgeber

Table of Contents

Philosophie für IT?
Stoizismus - Praktische Philosophie
Kernideen
Praktischer Nutzen
Weiterführende Gedanken und Leseempfehlungen
- Leseempfehlungen

Stoicism - Practical Philosophy for Your Daily IT-Life

Sun, 4 Sep 2022 00:00:00 +0000

This post is based on my talk Stoicism - A Practical Philosophy for Everyday IT. The video for this is linked on my talk page.

Philosophy for IT?

Why philosophy on a tech blog? One or the other may ask. For me, dealing with people is sometimes difficult, because I have a rather short fuse. Technology is simple and logical compared to the behavior of some colleagues. Especially in today’s working world, communication cannot be avoided. So I had to find a way for myself to deal professionally with challenges in this area.

I don’t remember where it was, but around 2018 I stumbled across Stoicism and have been studying it ever since. In the meantime, I am firmly convinced that this philosophy is an asset for anyone who even explores it. That’s why I tell everyone about it, who doesn’t want to hear it ;-)

Stoicism - Practical Philosophy

Philosophy has in many minds something to do with unworldly discussions that have no practical use in everyday life.

In contrast to this are the practical philosophies, to which also the Stoicism belongs. They deal explicitly with everyday life, or more precisely with interpersonal relationships. Stoicism in particular poses the following question:

How do I live my life so that I am overjoyed and it runs smoothly?

Stoic philosophy is about living a life in accordance with the Stoic virtues and becoming the perfect Stoic who can, among other things, use his or her judgment unclouded by emotion. Since we are human beings and emotions are part of our nature, this ideal is of course not attainable. But more about that later.

From this striving then happiness arises!

Let’s go to the next section, where I summarize the core statements of Stoicism.

Here please do not forget that I am a student of Stoicism and that there are additionally many different interpretations in the literature!

Core Ideas

A beautiful graphic summary of the core Stoic ideas is the Stoic triangle of happiness. High up is taking responsibility for one’s actions and reactions. But this is only possible when the two foundations Living in Aretè and Focusing on the Controllable have been mastered. In the middle is the highest goal: Eudaimonia. A compound word with the meaning of being at peace (Eu) with one’s inner self (Daimon).

Life in Areté

This corner of the triangle is about virtues and living by them. This means expressing these virtues in our actions.

Wisdom: In the sense of good judgment that is deliberate and not thoughtless.
Justice: This is about our relationship with our fellow human beings in which we should act with integrity and fairness
Courage: To act rightly in a situation. Against any resistance (even internal).
Self-discipline: In Stoicism, especially the appropriate response to emotions and strong desire in any respect.

It should be added that for Stoics all virtues are important. If one is not lived, then it becomes difficult to achieve eudaimonia. Nevertheless, all Stoics have found in their lives that they have problems to always act according to the virtues.

Seneca is a very famous example. As one of the richest men of his time, he was often accused of hypocrisy because he lived in abundance. He used to keep an evening journal in which he openly wrote about all the events of the day. He was aware of his mistakes. The important thing is to do your best!

Focus on the Controllable

Colloquially, the term stoic is equated with insensitivity. This is because stoics focus on the controllable. For this purpose, they divide things that happen into four categories:

No influence: Almost all external influences
Partial influence: For example, reactions to our behavior or even health .
Indifferent but preferred: Being rich or poor should have no influence on whether we live a stoic life. But being rich is definitely more pleasant ;-)
High Influence: The most important category, but also the smallest. Our judgment and actions

Only the fourth category we can really control. That is, complaining about the weather, for example, is not useful, since it can only be accepted. The art is to react in any situation in accordance with the stoic virtues.

Assume Responsibility

Without the two foundations, no responsibility can be taken. What really is our responsibility is how we react to an event. Thus, the weather (to stay with the example) doesn’t really care whether we are happy about it, indifferent, or annoyed. So it is our responsibility to decide how we feel.

That’s easy to write, but very difficult to implement! That’s why in the next sections we’ll look at the practical benefits of this and what stoic exercises are available to help us internalize the stoic happiness triangle.

Practical benefit

For me, the biggest practical benefit was the realization that we have a high impact on our reactions to external events. In particular, we see just the opposite in normal reactions on social media. This is where the empathy culture is at work. Every tweet is immediately reacted to sharply in the comments, up to and including insults. Very often unjustified, but also without the insight that the medium itself is very limited in its ability to express itself.

Figure 1. A stimulus is usually responded to instinctively without thinking.

Instead, we can take advantage of an effect that puts us back in control. There is a short period of time between the event and our spontaneous reaction to it. Personally, I only noticed it after I knew about it. So my advice is to observe yourself more closely. Chances are very good that it is like that for all people ;-). If we intervene at that exact moment, we can rationally consider what is the appropriate reaction to an event. In this way, we regain control and free ourselves from acting only emotionally.

Figure 2. The stoic approach to a stimulus of first stepping back and responding thoughtfully.

Stoic Exercises

To react appropriately in any situation, it is not enough to have the theoretical knowledge. This was already known to the ancient Stoics. That is why there is a wide range of stoic exercises that train us mentally to react appropriately.

I will present two of my favorite exercises, as they have helped me personally in everyday life.

Buy Serenity

When it comes to eating, I have a talent for spilling. This exercise has helped me turn off the negative voice in my head after such an incident and instead practice dealing with accidents. Until then, after every spill, I would ponder for a while how stupid it was. In the meantime I can laugh about most of it or I just don’t care. That’s why I buy myself serenity with this exercise. It goes like this:

As soon as a little mishap happens: Take the opportunity to observe yourself. Accept the feelings and then say to yourself during the Clean up: "For this little thing, I buy serenity!" The effects for me have been greater serenity in everyday life. Small mishaps are no longer which has made me more satisfied with myself.

Premeditatio Malorum

You know those people who plan everything exactly down to the last minute when they go on a trip? Only to realize that they have forgotten something important like toothpaste? I was exactly that kind of person. Now, it is in the nature of things to forget something when traveling. But most things are replaceable. Drugstore items are everywhere and so are larger items like power supplies for electronics.

The Premeditatio Malorum exercise helps with mental preparation for failure. It makes a big difference whether possible difficulties have been thought about or not. This allows for a more rational reaction in the situation, even if it has not yet been played out in the mind. Just the act of thinking about it helps. That’s why I advise not to think through everything completely, but only a few contingencies.

In the meantime, I am very relaxed when traveling, even when I really forgot my toothbrush and toothpaste.

Further Thoughts and Reading Recommendations

There is much more to discover in Stoicism than what I have described here. Every time I pick up a book on Stoicism and read it, I gain new insights. I can only recommend to start with the beginner-friendly book The Little Book of Stoicism by Jonas Salzgeber, it contains all important core statements of Stoicism in a very concentrated and understandable way.

Reading Recommendations

The Little Book of Stoicism - Jonas Salzgeber
The Practicing Stoic - Farnsworth
How to Think Like a Roman Emperor - Donald Robertson
Website of Nils and Jonas Salzgeber

Table of Contents

Philosophy for IT?
Stoicism - Practical Philosophy
Core Ideas
Practical benefit
Further Thoughts and Reading Recommendations
- Reading Recommendations

Architecture Decision Records Teil 3 - Im Kontext von arc42

Mon, 29 Aug 2022 00:00:00 +0000

Nachdem ich im letzten Artikel das Was und Wie von Architecture Decision Records erläutert habe, geht es diesmal darum Architekturentscheidungen in den Kontext des arc42-Templates einzubetten.

arc42 - Von oben nach unten auszufüllen?

Die Gliederung von arc42 sieht auf den ersten Blick angenehm und logisch aus (aus arc42):

1 Einführung und Ziele
2 Randbedingungen
3 Kontextabgrenzung
4 Lösungsstrategie
5 Bausteinsicht
6 Laufzeitsicht
7 Verteilungssicht
8 Querschnittliche Konzepte
9 Entwurfsentscheidungen
10 Qualitätsanforderungen
11 Risiken und technische Schulden
12 Glossar

Das liegt daran, dass diese Struktur für Lesende ist!

Lesende interessiert nicht, welche Qualitätsanforderungen an ein System gestellt wurden und wie diese zur vorhandenen Softwarearchitektur geführt haben. Für sie ist nur das Ergebnis wichtig. Außer es gibt Probleme mit dieser Lösung, dazu aber später mehr.

Wie erstelle ich die Dokumentation als Schreibende*r

Wird die Architekturdokumentation gerade erstellt, sollte anders vorgegangen werden. Ralf und ich haben dazu im weiter unten verlinkten Talk die folgende Bearbeitungsreihenfolge für die Kapitel vorgeschlagen:

1 → 2 → 3 → 10 → 9 → …

Kapitel 1-3 sind notwendig, um festzulegen WAS gebaut werden soll, WELCHE Randbedingen nicht änderbar sind und in WELCHEM Kontext das zu bauende System operiert. Im Grund genommen ist es der Vertrag, der mit Kunden geschlossen wird.

Bevor nun die Architektur entworfen werden kann, ist es sinnvoll die Qualitätsanforderungen abzuklären. Das Ergebnis sollte ein gewichteter Qualitätsattributbaum sein, der die maximal fünf höchstpriorisierten Qualitätsattribute enthält. Die folgende Abbildung zeigt einen Ausschnitt eines solchen Baumes für ein System, das ich betreut habe.

Für das System dieses Qualitätsattributsbaumes waren die Qualitätsattribute sehr klar, dank zweier Fachexpert*innen, die sich in ihrem Bereich und mit dem abzulösenden Altsystem sehr gut auskannten. In den meisten Fällen wird es eher darauf hinauslaufen mit unklaren Qualitätsanfordungen wie "Das System mus performant sein!" konfrontiert zu werden. Oder es werden mehrere sich widersprechende Qualitätsattribute gefordert. Hier hilft es Vergleiche mit anderen Systemen heranzuziehen. Im Falle von Performanz kann von Kundenseite zum Beispiel ein System benannt werden, dass als performant empfunden wird.

Entscheidungen treffen im Hinblick auf Qualitätsanforderungen

Erst jetzt kann ich daran gehen die Architektur zu entwerfen und die Entwurfsentscheidungen als ADRs zu dokumentieren. Es empfiehlt sich am Ende eines jeden ADRs eine weitere Überschrift einzufügen in der die, von der Entscheidung betroffenen, Qualitätsattribute aus Kapitel 10 verlinkt werden.

Note	Hin und wieder kommt es vor, dass eine Entscheidung auf kein Qualitätsattribut einzahlt. Hier ist zu überprüfen, ob sie architekturrelevant ist und in arc42 dokumentiert werden sollte. Eventuell ist es auch eine Randbedingung.

Warum Qualitätsattribute und Entwurfsentscheidungen in so späten Kapiteln?

Lesende interessieren sich normalerweise nicht dafür auf welcher Grundlage ein System gebaut wurde. Viel interessanter ist doch zu sehen WIE es aufgebaut ist. Architekturdiagramme wie die Microservicearchitektur von Netflix zum Beispiel wirken imposant und eindrucksvoll. Die Kompromisse im Betrieb und die Komplexität im Entwicklungs- und Deploymentprozess treten in den Hintergrund.

Für Softwarearchitekturschaffende oder falls es Probleme gibt sind Kapitel neun und zehn aber hochinteressant. Denn dort steht im besten Fall nachvollziehbar WARUM ein System so gebaut ist und welche Entwurfsentscheidungen dazu geführt haben, dass ein gewisses Problem aufgetreten ist. Nicht selten sind unklare Qualitätsanforderungen die wahre Ursache für Schwächen des Systems!

Wie geht es weiter?

In diesem Blog habe ich beschrieben, welche Bedeutung Architekturentscheidungen im Kontext von arc42 einnehmen und wie die Bearbeitungsreihenfolge bei der Erstellung eines Systems aussehen sollte.

Im nächsten Post gehen wir endlich auf die Technik ein, mit der Architekturentscheidungen effizient gesammelt und verwaltet werden können.

Wer lieber ein Video zu arc42 und Architekturentscheidungen angucken will dem empfehle ich schamlos meinen Vortrag mit Ralf:

Table of Contents

arc42 - Von oben nach unten auszufüllen?
Wie geht es weiter?

JavaLand 2022 Gedächtnistörtchen

Sun, 20 Mar 2022 00:00:00 +0000

Im JavaLand gab es diesmal super leckere Törtchen - wohl auch Petit Fours genannt. Ich dachte erst, die würden viel zu süß sein, aber nein. Nach anfänglich einem einzelnen, konnte ich mich auf drei plus Espresso steigern.

Diese kleinen Biester waren so lecker, dass ich, kaum war ich daheim angekommen, versuchen musste sie mit meinen limitierten Backkünsten nachzumachen.

Hier mein Rezept

Zutaten

biskuitboden

❏ 200g Zucker
❏ 5 Eier
❏ 150g Mehl
❏ 50g Speisestärke
❏ 1/2 Pck. Backpulver
❏ 1 Pck. Vanillezucker

Füllung und Schoko-Raspeln

❏ 200g sehr weiche Butter
❏ 300g Milch
❏ Dr. Oetker TortenCreme Vanilla

Glasur

❏ 250g Puderzucker
❏ 1 Zitrone

Umhüllung

❏ 1 geheime Zutat

Rezept

Biskuitboden

Den Biskuitboden kannst Du auch fertig gebacken und geschnitten kaufen. Ich habe ihn mal wieder selbst gebacken.

Mit dem Thermomix™ ist er auch ganz schnell selbst gemacht.

Backofen auf 180°C vorheizen
Den Boden einer Springform (Ø 26 cm) mit Backpapier auslegen. Du kannst das Backpapier einfach über den Boden legen und mit dem Rahmen der Springform einspannen. Das überstehende Backpapier am Besten nicht abschneiden.
Rühraufsatz (Schmetterling) in den Thermomix™ einsetzen
5 Eier in den Mixtopf aufschlagen
2 Minuten bei 37°C auf Stufe 4 verrühren
200g Zucker und 1 Pkg. Vanillezucker zugeben
10 Minuten bei Stufe 4 weiter aufschlagen
150g Mehl, 1/2 Pck. Backpulver, 50g Kakaopulver und 50g Speisestärke rechts und links neben den Rühraufsatz (Schmetterling) zugeben
4-8 Sekunden auf Stufe 3 unterheben
Rühraufsatz(Schmetterling) entfernen
Mit dem Spatel das Mehl noch etwas mehr unterheben
Biskuitteig in die vorbereitete Form geben und 20-25 Minuten bei 180°C backen
Biskuitteig mindestens 10 Minuten abkühlen lassen
waagerecht mit vier Schnitten in fünf Böden schneiden

Zum Schneiden der Torte habe ich den Tortenschneider aus dem Ikea-Set SMAKSAM genutzt :-).

Tortencreme

Rühraufsatz (Schmetterling) in den Thermomix™ einsetzen
Dr. Oetker TortenCreme Vanilla in den Mixtopf geben
200g sehr weiche Butter und 300g Milch nach Angabe auf der Dr. Oetker Packung zugeben
Mixer langsam von Stufe 1 bis Stufe 5 anstellen und ca. 3 Minuten aufschlagen.

Zusammenbau

Verteile die TortenCreme auf den Bisquitböden, so dass ein entsprechender Stapel aus Schichten entsteht. Die TortenCreme muss dabei nicht ganz die Ränder erreichen, denn nach dem Zusammenbau wird aus der runden Torte ein Quadrat herausgeschnitten. In diesem Bereich sollte die Creme also gut verteilt sein.

Vor dem Schneiden aber erstmal die Schichttorte für 2 Stunden in den Kühlschrank geben, damit die TortenCreme fest wird.

Nun aus der Schichttorte ein großes Quadrat rausschneiden. Der Rest ist "Abfall" und kann jetzt vernascht werden.

Vor Dir liegt nun ein Quadrat aus leckeren Creme- und Biskuit-Schichten. Dieses unterteilst Du nun mit 6 Schnitten in 16 kleinere Quadrate.

Löse die Quadrate vorsichtig vom Backpapier und setze sie auf z.B. ein Backblech (sollte in Deinen Kühlschrank passen)

Die Glasur

Nun gibst Du den Puderzucker in ein Schälchen und rührst mit ein wenig Zitronensaft die Glasur an. Achtung - nicht zu viel Zitronensaft, damit die Glasur nicht zerfliesst.

Jetzt kommt der Spritzbeutel aus dem Ikea-Set SMAKSAM zum Einsatz. Mit der breiten Tülle wird der Zuckerguss in drei breiten Strichen aufgetragen und eventuell noch mit irgendwas dekoriert.

Schnell wieder in den Kühlschrank, damit der Zuckerguss fest wird. 30 Minuten sollten hier reichen.

Umhüllung

Hier kommt die geheime Zutat zum Einsatz. Leider kenne ich sie nicht. Ich habe anfang auf Marzipan getippt. Das lässt sich aber nicht so dünn verarbeiten und ist recht dunkel. Also habe ich es nochmal mit Fondant probiert - kommt dem Original leider auch nicht so nah.

Dennoch, hier ist, was ich gemacht habe.

Weisses Fondant möglichst dünn (ca. 1mm) als breiten Streifen (ca 9-12cm) ausrollen.
Die obere und rechte Kannte mit einem Messer gerade schneiden.
Törtchen rechts anlegen, 3x nach links drehen und die rechte und untere Kannte mit einem Messer schneiden.
Anschliessend das Törtchen mit dem so abgemessenen Fondant ummanteln.
15x wiederholen.

Wieder nach Belieben jedes Törtchen verzieren.

Guten Appetit!

PS: Für Hinweise, wie man das Rezept verbessern kann (vor allem die Ummantelung) bin ich sehr dankbar.

PS PS: an Stelle der TortenCreme kann man natürlich auch richtige Buttercreme verwenden, so wie sie in meinem anderen Rezept beschrieben ist.

Table of Contents

Zutaten
Rezept

Remote Dev Environments

Mon, 22 Nov 2021 00:00:00 +0000

Do you remember the times when the biggest challenge to compile a project was to set up the correct build environment with all required dependencies?

The flexibility you have as a developer with current technologies is amazing. Not only that you can setup your dev environment with docker but you also chose where to run it. You can even choose to run your IDE on a remote machine.

Let’s take a look at the options you have with Visual Studio Code or short VS Code.

Let’s start with the standard way you use VS Code for development. You download and install it. Then you run it locally, clone your project from a git repository and develop locally. You have to ensure that everybody who uses the code has all needed external dependencies like build tools installed.

That’s ok, but let’s take a look how we can help others to get the right start with the right environment for your code.

Move your environment to a container

The next logical step is to move your environment to a container.

The VS Code team started soon to experiment with splitting up the IDE into a frontend and a server backend. When you start VS Code on a Windows environment from within the Windows Subsystem for Linux (WSL), it starts the backend server in WSL and then connects to the frontend which runs natively on Windows.

With the Remote Containers plugin, you can use this mechanism to start a container with your well defined environment, get the server part of VS Code installed there and connect from the frontend to it.

Put a devcontainer.json in your repository and VS Code will use this container definition as your dev environment.

Move your environment to a remote machine

Now that your development environment runs independent of your local VS Code instance, you can even move it to a remote machine. Maybe one with more power. And it is easier than you think - with gitpod.io.

Gitpod is basically a free and open source IDE for GitHub. Choose any github repository and prefix the URL with gitpod.io#. This will invoke gitpod which clones the selected repository to a remote container, and asks you if you want to connect the remote container to your local VS Code.

Move your IDE to a remote machine

If you’ve followed me and gave Gitpod a try, you will have noticed that it not only starts your repository in a remote container. It also starts an instance of VS Code as web based application!

As a result, you have a full-blown remote development environment which even works with low bandwidth connections. Only some keystrokes and characters go over the wire. Your code is always executed on a performant remote machine.

With a .gitpod file in your repository, you can even define the container to which the repository is cloned.

I hope this article gave you some new ideas on how to set up your next dev environment. Have fun coding!

Architecture Decision Records Teil 2 - Das strukturierte Format für Architekturentscheidungen

Tue, 2 Nov 2021 00:00:00 +0000

Nachdem ich im letzten Artikel hergeleitet habe, warum es eine gute Idee ist Entscheidungen zu dokumentieren, will ich heute das Was und das Wie beschreiben.

Was sollte ich dokumentieren?

Basierend auf meinen Erfahrungen lohnt es sich zwei Dinge zu dokumentieren.

Zum Ersten finde ich es wichtig in einem Team Klarheit über die Technologientscheidungen zu haben. Wir sind alle Individuen mit bestimmten Vorlieben. In meinem jetzigen Team haben wir ein buntes Gemisch aus Technologiepräferenzen. Um unbewusste Ablehnung von implementierten Lösungen durch andere Teammitglieder zu vermeiden und um Klarheit über den Entscheidungsvorgang zu bekommen, dokumentieren wir diese Entscheidungen.

Außerdem dokumentieren wir alle Architekturentscheidungen. Aber was ist das eigentlich genau? Dafür lohnt sich eine Definition, denn Softwarearchitektur selbst ist schon ein schwieriger Begriff.

Architekturentscheidungen wirken sich direkt auf die Softwarearchitektur aus und sind später nur schwer oder gar nicht mehr änderbar. Sie definieren das Softwaresystem maßgeblich und zahlen im besten Fall direkt auf die Qualitätsanforderungen ein.

Architekturentscheidungen sind immer ein Kompromiss aus verschiedenen Qualitätsanforderungen. Letztere sollten priorisiert vorliegen, so dass die Entscheidungen immer zugunsten der höher Priorisierten getroffen wird. Das ist wichtig, da es oft zum Konflikt zweier Qualitätsanforderungen kommt.

Dazu ein kleines Beispiel: Das Softwaresystem soll als Priorität 1 hohe Security bereitstellen. Außerdem soll es für den Benutzer leicht zu bedienen sein als Priorität 2. Es steht die Entscheidung an, wie die Benutzerauthentifizierung passieren soll. Hohe Sicherheit bietet die Zwei-Faktor-Authentifizierung, die aber dummerweise für den Benutzer etwas umständlicher ist als die Kombination Benutzername und Passwort. Hier schlägt Priorität 1 die Priorität 2 und es wird die Zwei-Faktor-Authentifizierung implementiert!

Wie dokumentiere ich Entscheidungen?

Für mich müssen die folgenden Anfordungen an die Dokumentation einer Entscheidung erfüllt sein:

Schnell zu erstellen
Leicht zu lesen
Chronologisch nachzuvollziehen

Entering Architecture Decision Records (ADR)

Ein hervorragendes Format hat Michael Nygard in einem Blogpost beschrieben: Die Architecture Decision Records. Er schlägt vor, Entscheidungen nach einem festen Schema in einzelnen Dateien abzulegen. In seinem Team ist das als Dateien in einem Repository im Markdown-Format. Für ihn funktioniert das sehr gut in agil arbeitenden Teams. Sein Format sieht wie folgt aus:

Title: Durchnummeriert in der Form ADR-XXX: Nomenphrase
Context: Alle Fakten, die auf diese Entscheidung Einfluss haben. Politisch, sozial, technlogisch etc.
Decision: Die Entscheidung in einem bis maximal zwei Sätzen in aktiver Sprache
Status: Offen, Beschlossen, Ersetzt oder zurückgenommen
Consequences: Alles was aus der Entscheidung folgt. Positiv wie negativ

Dieses Format kann in einer Datei in einem git-Repository oder als Wikiseite mit Ausfüllhinweisen als sogenanntes ADR-Template abgelegt werden. Bei Bedarf wird es kopiert und muss nur ausgefüllt werden. Der Aufwand wird somit stark reduziert.

Für mein Team angepasstes ADR-Format

In meinem Team setzen wir ein leicht angepasstes Format ein.

Title
Decision
Status
Context
Consequences
Alternatives

Wir empfinden es als wichtig, die Entscheidung sowie den Status prominent zu platzieren. Sie sind normalerweise das Wichtigste und Interessanteste für den Leser. Außerdem haben wir noch den letzten Punkt Alternatives hinzugefügt, da er bei technologischen Entscheidungen hilft, die Alternativen in der Diskussion näher zu beleuchten. Wird eine Entscheidung zurückgenommen oder ersetzt stellte dieser Punkt schon ein paar Mal den Ausgangspunkt für weitere Evaluationen dar.

Weitere Formate

Es gibt noch zahlreiche andere Varianten von ADR-Templates. Auch welche, die sich weniger technologisch orientieren. Ein guter Einstiegspunkt dafür bietet die ADR Organization auf Github.

Wie geht es weiter?

In diesem Blog habe ich beschrieben, wie Entscheidungen strukturiert mit dem ADR-Template dokumentiert werden können.

Im nächsten Post gehen wir auf das arc42 Architekturdokumentationstemplate ein und sehen uns an, wie wir dort die Architecture Decision Records einsetzen.

Table of Contents

Was sollte ich dokumentieren?
Wie dokumentiere ich Entscheidungen?
Wie geht es weiter?

Architecture Decision Records Teil 1 - Warum Entscheidungen dokumentieren?

Sun, 11 Apr 2021 00:00:00 +0000

Entscheidungen zu dokumentieren stellt meiner Erfahrung nach Verbindlichkeit und Transparenz her. Um Architekturentscheidungen zu dokumentieren hat sich für mich ein Format namens Architecture Decision Record (kurz ADR) bewährt.

Im Rahmen dieser Artikelserie betten wir die Architecture Decision Records in den größeren Rahmen der Architekturarbeit ein. Dabei gehe ich insbesondere auf den Kontext des Dokumentationstemplates arc42 und dessen Einsatz im DevOps-Umfeld ein.

Wir sehen uns dazu auch intensiver die Technik an, mit der dokumentiert wird. Hier kommen AsciiDoc, Microsites und Git zum Einsatz.

Aber starten wir zuerst mit dem Warum. Warum ist es eine gute Idee, Entscheidungen zu dokumentieren?

Undokumentierte Entscheidungen - Ein Problem auf unterschiedlichen Ebenen

Undokumentierte Entscheidungen sind oft die Regel. Meistens bleiben sie eine lange Zeit unbemerkt oder kommen nie wieder zur Sprache. Interessant wird es, wenn an einer Stelle die Frage gestellt wird: Warum ist das so?

Dabei ist dieses Problem nicht nur auf technische Dinge beschränkt. Auch zwischenmenschliche Aspekte der Zusammenarbeit sind betroffen.

Technische Entscheidungen

Technik kann alles Mögliche umfassen. Ich nehme mal das Beispiel einer Frameworkentscheidung für einen Microservice heraus.

Inzwischen gibt es zu jeder Programmiersprache unzählige Frameworks, um einen Microservice zu implementieren. Interessanterweise gibt es in einem Team normalerweise mehrere Meinungen, welches Framework das Beste ist. Deswegen sollte so eine Entscheidung dokumentiert werden. Wichtig hierbei aus meiner Sicht: Die untersuchten Alternativen mitdokumentieren.

In unserem Team hatten wir genau diese Entscheidung zur Wiedervorlage. Wir waren mit unserer alten Implementierung unzufrieden und haben uns einige Alternativen angesehen und sie mit Performance-Tests und Proof-Of-Concepts evaluiert. Die folgende Entscheidung beruhte auf der erstellten Datenbasis. Alle Alternativen sind in der Entscheidungsdokumentation zu finden und für jeden nachvollziehbar.

Zwischenmenschliches

Zwischenmenschliches klingt meistens banal, hat aber im Alltag große Auswirkungen auf Arbeitsmoral und Motivation. Dazu ein Beispiel:

In meinem Team fehlt anscheinend eine Regel, wie mit temporärer Abwesenheit ohne Krankmeldung umgegangen wird. Ein Teamkollege von mir war nur zum Daily anwesend, aber dann den ganzen Tag nicht mehr in der Teamkommunikation zu sehen. Am Ende des Tages war ich besorgt und leicht ärgerlich zugleich. Mir war nicht klar, wie er den Tag verbracht hat oder ob etwas passiert ist.

Aus meiner Sicht brauchen wir dafür im Team eine dokumentierte Entscheidung, wie wir mit solchen Abwesenheiten umgehen. Ziel ist nicht Kollegen:innen zu gängeln, wenn sie sich nicht daran halten. Aber ich kann dann so darauf hinweisen: "Sieh mal, so hatten wir das entschieden, warum machst Du das nicht so?"

Architekturentscheidungen

Eine besondere Rolle nehmen Entscheidungen ein, die sich auf die Softwarearchitektur eines Softwaresystems beziehen. Meine Definition dieser Entscheidungen ist die Folgende: "Eine Architekturentscheidung ist im Nachhinein potentiell teuer bis gar nicht zu ändern und bezieht sich auf die Qualitätsanforderungen eines Systems"

Aus meiner Erfahrung sind Architekturentscheidungen dann gefährlich wenn sie unbewusst getroffen werden. Unbewusst werden sie getroffen, wenn ein System einfach so entsteht. Es wird an allen Stellen gearbeitet, aber nie darüber geredet, was mit dem System erreicht werden soll. Sehr oft kommt später die Frage auf: "Warum ist das so gemacht worden?"

In unserem Team wurde explizit die horizontale Skalierbarkeit als Qualitätsanforderung gesetzt und daraufhin ein Kollege mit der Umsetzung einer API beauftragt. Am Ende kam eine hochperformante Implementierung heraus, die leider für den Rest des Teams unwartbar war. Hier wurde die Qualitätsanforderung Wartbarkeit missachtet. Das hätte durch Transparenz in der Entscheidungsfindung vermieden werden können.

Das Besondere an DevOps-Teams

Entscheidungen zu dokumentieren und vor allem zu vergemeinschaften ist in einem DevOps-Team sehr wichtig. Um als Team effektiv zu agieren sollte der Kommunikationsaufwand innerhalb des Teams klein gehalten werden. Aus meiner Sicht ist die Maximalgröße von sieben Menschen schon fast zu groß, da die Kommunikationskanäle im Team sehr viele sind (siehe dazu Kommunikationsbeziehungen).

Um mit dieser kleinen Anzahl an Menschen den gesamten Entwicklungszyklus von der Anforderungserhebung beim Kunden bis zum Betrieb des Systems abzudecken ist effektive Kommunikation unabdingbar. Besonderes Augenmerk ist hier aus meiner Erfahrung heraus auf Einigkeit bei architektonischen und technischen Entscheidungen zu legen.

Nichts wirkt sich destruktiver auf das Team aus, als eine im Stillen nicht mitgetragene Entscheidung!

Wie geht es weiter?

Inzwischen sollte klar geworden sein, warum ich es wichtig finde Entscheidungen zu dokumentieren.

Doch wie geht das eigentlich effektiv und effizient?

Im nächsten Post sehen wir uns ein Format namens Architecture Decision Records an. Das eignet sich speziell für Architekturentscheidungen, kann aber auch auf andere Entscheidungen adaptiert werden.

Table of Contents

Undokumentierte Entscheidungen - Ein Problem auf unterschiedlichen Ebenen
- Technische Entscheidungen
- Zwischenmenschliches
Architekturentscheidungen
Das Besondere an DevOps-Teams
Wie geht es weiter?

Schwarzwälder Kirschtorte

Sun, 21 Feb 2021 00:00:00 +0000

Jedesmal, wenn ich zu Besuch bei meiner Großmutter war, konnte ich wählen, welche Torte es Sonntags geben sollte. Zur Auswahl standen Schwarzwälder Kirsch und Prinzregenten. Meist wurde es die Schwarzwälder Kirsch. Das Originalrezept ist leider nicht überliefert, es war aber natürlich bei weitem Besser als alles, was ich an Schwarzwälder Kirsch sonst vorgesetzt bekommen habe. Das lag zum einen an der leckeren Buttercreme (nein, Sahne geht gar nicht!) zum anderen aber auch an den leckeren handgeraspelten Schoko-Raspeln.

Letzten Monat habe ich mir die Zeit genommen und versucht das Rezept interativ wieder herzustellen. Ich habe also Rezepte verglichen, gebacken, probiert und wieder von Vorne angefangen. Das Ergebnis findest Du nun hier als Rezept für den Thermomix™.

Fotos Deiner Umsetzung bitte gerne auf Twitter mit dem Hashtag #OmasSchwarzwaelderKirsch teilen.

Zutaten

Tortenboden

❏ 200g Zucker
❏ 5 Eier
❏ 150g Mehl
❏ 50g Kakaopulver
❏ 50g Speisestärke
❏ 1/2 Pck. Backpulver
❏ 1 Pck. Vanillezucker

Füllung und Schoko-Raspeln

❏ 600 g Milch
❏ 120 g Zucker
❏ 2 Pck. Vanillepuddingpulver
❏ 1 Prise Salz
❏ 330 g Butter, Zimmertemperatur, in Stücken
❏ 1 Glas Sauerkirschen
❏ 200g Blockschokolade

Rezept

Anfangs habe ich den Fehler gemacht mit dem Tortenboden anzufangen. Dadurch ergeben sich zu lange Wartezeiten und das Backen dauert fast einen Tag. Deshalb fangen wir nun mit der Buttercreme an.

Pudding (für die Buttercreme)

Butter aus dem Kühlschrank nehmen, damit sie Zimmertemperatur annehmen kann.
600g Milch, 120g Zucker, 2 Pck. Vanillepuddingpulver und eine Prise Salz in den Mixtopf geben
10 Sekunden auf Stufe 4 verrühren
7 Minuten bei 100°C auf Stufe 2,5 aufkochen
in eine große Schüssel umfüllen, und ein Stück hitzebeständige Frischhaltefolie direkt auf den Pudding legen, damit dieser keine Haut bilden kann
den Pudding ca. 2 Stunden auf Zimmertemperatur abkühlen lassen

Dunkler Wiener Boden

Den Wiener Boden kannst Du auch fertig gebacken und geschnitten kaufen - dann ist er aber nur halb so gut. Mit dem Thermomix™ ist er auch ganz schnell selbst gemacht.

Backofen auf 180°C vorheizen
Den Boden einer Springform (Ø 26 cm) mit Backpapier auslegen. Du kannst das Backpapier einfach über den Boden legen und mit dem Rahmen der Springform einspannen. Das überstehende Backpapier am Besten nicht abschneiden.
Rühraufsatz (Schmetterling) in den Thermomix™ einsetzen
5 Eier in den Mixtopf aufschlagen
2 Minuten bei 37°C auf Stufe 4 verrühren
200g Zucker und 1 Pkg. Vanillezucker zugeben
10 Minuten bei Stufe 4 weiter aufschlagen
150g Mehl, 1/2 Pck. Backpulver, 50g Kakaopulver und 50g Speisestärke rechts und links neben den Rühraufsatz (Schmetterling) zugeben
4-8 Sekunden auf Stufe 3 unterheben
Rühraufsatz(Schmetterling) entfernen
Mit dem Spatel das Mehl noch etwas mehr unterheben
Biskuitteig in die vorbereitete Form geben und 20-25 Minuten bei 180°C backen
Biskuitteig mindestens 10 Minuten abkühlen lassen
waagerecht mit zwei Schnitten in drei Böden schneiden

Schokoraspeln

Wartezeiten kannst Du prima mit dem Raspeln der Schokolade füllen. Lege dazu die Blockschokolade auf ein Schneidebrett, nimm ein großes scharfes Messer und schneide ganz dünne Raspeln ab, bis die kompletten 200g Blockschokolade geraspelt sind.

Kirschen

Auch die Kirschen kannst Du als Pausenfüller schon mal abtropfen lassen.

Buttercreme

Wenn nun der Pudding abgekühlt ist (Butter und Pudding müssen ca. Zimmertemperatur haben), mit der Buttercreme fortfahren.

330g Butter in Stücken in den Mixtopf geben
1 Minunte auf Stufe 4 aufschlagen
nun den Thermomix™ auf 2,5 Minuten bei Stufe 2,5 einstellen
nach und nach den Pudding auf das laufende Messer zugeben
10 Sekunden bei Stufe 6 die Creme glatt rühren

Zusammenbau der Torte

Mit einem Tortenretter legst Du nun den untersten Boden auf zwei Stück Backpapier, die sich in der Mitte ca. 2 Zentimeter überlappen. Mit diesem Trick kannst Du das Backpapier zum Schluss leichter unter der Torte rausziehen.

Du solltest jetzt ca. 1050g Buttercreme im Thermomix haben. Bei der lezten Zubereitung habe ich die Buttercreme nach Gefühl aufgeteilt, ich denke aber, wir sollten die eingebaute Waage nutzen um es uns zu erleichtern. Die Zahlen sind also momentan Schätzungen.

verteile 300g Buttercreme auf den ersten Boden. Lücken zum Rand hin können später noch leicht verfüllt werden.
lege 12 ausgewählte Kirschen für die Dekoration beiseite
verteile die restlichen abgetropften Kirschen auf der Buttercreme
setze den zweiten Boden auf den ersten
verteile wieder 300g Buttercreme auf dem Boden
setze den dritten Boden auf den zweiten
fülle eine Granierspritze etwa zur Hälfte mit Buttercreme
verteile die restliche Buttercreme auf der Torte und über die Seiten. Dabei schliesst Du eventuelle Lücken am Rand der Tortenböden. Keine Angst, das muss nicht super aussehen - die Schokoraspeln werden einiges Kaschieren.
verteile nun auf der Torte Schokoraspeln, bis die Oberfläche vollständig bedeckt ist
nimm nun ein breites Messer und "streiche" jeweils einige Schokoraspeln von unten nach oben über die Ränder der Torte, bis auch der Rand mit Raspeln bedeckt ist.
zum Schluss setzt Du noch 12 Tupfer Buttercreme mit der Garnierspritze auf den Rand der Torte und verzierst sie mit jeweils einer Kirsche.
stelle die Torte in den Kühlschrank

Nach ca. zwei Stunden im Kühlschrank ist die Buttercreme fest und die Torte somit servierfertig. Richtiggute schmeckt sie allerdings, wenn sie ein bis zwei Tage durchgezogen ist.

Guten Appetit!

Table of Contents

Zutaten
- Tortenboden
- Füllung und Schoko-Raspeln
Rezept

Dynamic AsciiDoc with Groovy and jBake

Wed, 11 Nov 2020 00:00:00 +0000

Did you ever wish to be able to create more "dynamic" documents with AsciiDoc?

Attributes

Attributes are already quite nice. They let you create parameterized docs which you can easily update. One example on how to use attributes are URIs for links in your document.

For example, if you have a reference like

https://fiveandahalfstars.ninja/blog/2020/greenscreen_fuer_online-besprechungen_selbst_bauen[latest post by Johannes]

you can replace this with the following, more readable version

:uri1: https://fiveandahalfstars.ninja/blog/2020/greenscreen_fuer_online-besprechungen_selbst_bauen

{uri1}[latest post by Johannes]

And whenever the link has to be updated (because Johannes published something new), you just have to update the attribute and the link will change wherever it was used.

jBake Meta-Data

In additon to the AsciiDoc attributes, jBake comes with a Metadata-Header. We use this for instance to tag a post with an author. These meta-data snippets are also AsciiDoc attributes. In addtion, you can access them in the page templates. Here is a snippet from our postpreview.gsp template:

<img src="images/profiles/${post.author}.jpg" alt="${post.author}">

jBake Data-Model

Another concept of jBake is to first parse and store all content in a local database and only then apply the templates.

This turns every blog post into one line of a data table.

Chunks of Data

Now, what happens if you have more data? Or maybe you don’t want to create an extra file for each data entry?

Maybe you want to display the latest measurements of your IoT device or you have a list of talks (like we have) and you want to render them?

In case of the talks, we started out to maintain them as pure AsciiDoc files. That is ok for a start. The list might grow quite quickly and as soon as you want to display such a (long) list in another way, you need to reformat all entries.

In case of the measurements of your IoT device, it is even more obvious - you just don’t want to type the measuremts by hand into an AsciiDoc table.

Two Solutions

To automate things, there are two solutions.

One: a Generator

You already build your docs, so why not convert some json formatted data into AsciiDoc before you hand it over to jBake? In fact, this is a pretty easy approach, depending on the language you use. And for both use cases, it is easier to maintain your data as json file than as AsciiDoc (which is in fact not a data-format 😁).

Code for this could look somthing like this:

generate.groovy

//read data file
def json = new File(content.datafile).text
def data = new groovy.json.JsonSlurper().parseText(json)
//iterate over data and output list of talks
def asciidoc = ""
data.talks.each { talk ->
    asciidoc += """\
== ${talk.date} ${talk.title}

${talk.abstract}

"""
}
new File("talks.adoc").write(asciidoc)

You can then include the result in any .adoc-file. As you can see, it is now easy to (for instance) add the location where the talk will happen or any other detail.

Two: Dynamic AsciiDoc

Do you know PHP, JSP or GSP? With those server-side template languages, you have a syntax which lets you add dynamic elements to an otherwise static template. The generator code seen above could look like

talks.adoc

:jbake-type: gsp
:jbake-dataFile: ./data/talks.json

<% talks.each { talk -> %>

== ${talk.date} ${talk.title}

${talk.abstract}

<% } %>

The main difference is now, we inject code within <% … %> into our document instead the other way around. The code shown could be embedded in a larger document and since this is part of the document, you don’t have to start an additional build step before your build your docs.

The :jbake-dataFile: specifies where our data comes from.

jBake already implements GSP-Templates. Groovy Server Pages. These allow us to use Groovy code within our templates. And this allows us to use also the body of a document as GSP-Template.

Such a template looks like this:

<%include "header.gsp"%>
<body onload="prettyPrint()">
<div id="wrap">
    <%include "menu.gsp"%>
    <div class="container">

        <%
            def template
            def body = ""
            try {
                //read data file
                def json = new File(content.datafile).text
                def data = new groovy.json.JsonSlurper().parseText(json)
                //combine data and template
                def engine = new groovy.text.SimpleTemplateEngine()
                // clean up the body
                // (Asciidoctor replaces a bit too much)
                body = content.body
                        .replaceAll("&#8594;", "->")
                        .replaceAll("&#8656;", "<=")
                        .replaceAll("&lt;", "<")
                        .replaceAll("&gt;", ">")
                        .replaceAll("&amp;", "&")
                template = engine.createTemplate(body).make(data)
            } catch (Exception e) {
                out << "<pre>"
                out << e.message
                out << body
                out << e.getStackTrace().join("\n")
                out << "</pre>"
            }
        %>

        <%= template %>

    </div>
</div>
<%include "footer.gsp"%>

et voilà! Dynamic AsciiDoc!

The solution shown is a good solution for some use cases, like the ones mentioned above. Please keep in mind that the resulting AsciiDoc is not standard conform anymore and will only work with your jBake system. The generator approach might be a better solution in certain situations.

Table of Contents

Attributes
jBake Meta-Data
jBake Data-Model
Chunks of Data
Two Solutions
- One: a Generator
- Two: Dynamic AsciiDoc

Build your own Webcam - Part 3

Sat, 29 Aug 2020 00:00:00 +0000

We are still in a situation where working from home is the normal situation.
And while maybe you already got enough webcams to solve your conferencing problems, here are two new ideas.

1. HDMI Capture Cards

A HDMI capture card was always something I dreamed of but 120 € was too much to just play around with it.

Now, the price has changed.

There are currently some new chinese, no-name capture cards on the market for as low as 15 €!

Are they worth it?

Yes! They are able to capture HDMI at 1920x1080 with 30fps and only a short delay. If you lower the resolution, you even get 60fps.
And what's best about them, you plug them in as USB device and they pretend to be a webcam.
No additional drivers needed.

Just search on amazon for "HDMI capture card" and you'll find them.
There are even once with a HDMI output to connect an additional monitor.

What does this have to do with a Webcam?

Glad you ask ;-)

With a HDMI Capture Card, you can...

... use any DSLR with HDMI out as Webcam. And since the Canon driver is only available for Windows, you can even use Canon cameras with your Mac
... use a second PC to do the heavy OBS lifting and feed the output as Webcam to the PC on which you do your video conferencing.
... use a tablet like the iPad with HDMI out as white board for your sessions.

Isn't that cool?

2. Use your Pi-Zero as real Webcam

In my last blog posts, I tried to set up a pizero based webcam, but it needed to many additional drivers and the performance varied over the network.
I didn't think of the feature that the pizero (and only the pizero, no other model yet) can act as an usb device itself.
But now I found a great blog post which desccribes exactly this: turn the pizero in a usb webcam.
Since modern operating systems already include drivers for webcams, no additional drivers are needed.

The results as presented in the video from the blog author look very promising:

Now, this will allow me to create an IR-Webcam with th PiNoIR camera - that'll be fun!

PS: thanx to Johannes Dienst for fixing my typos :-)

Greenscreen für Online-Besprechungen selbst bauen

Fri, 3 Jul 2020 00:00:00 +0000

Wer sich mit dem Thema Video-Streaming beschäftigt kennt sie unweigerlich: Greenscreens. Aber auch in der Zeit der Online-Meetings und Zuhausearbeit kann mit ein klein wenig Aufwand ein Online-Meeting aufgepeppt werden.

In diesem Beitrag zeige ich, wie ich es unter ungünstigen Bedingungen geschafft habe das folgende Ergebnis in Microsoft Teams zu erreichen.

Figure 1. Endergebnis in Microsoft Teams mit virtueller Kamera aus OBS Studio

Voraussetzungen

Wie auf dem unteren Bild zu sehen, ist mein Platzangebot sehr gering. Da ich direkt unter dem Dach mein Arbeitszimmer habe, fällt die Möglichkeit weg, den Greenscreen weit von mir weg zu platzieren. Das hat die folgenden Nachteile:

Die Wahrscheinlichkeit des sogenannten Greenspills, also dem Zurückwerfen der grünen Farbe auf mich, ist sehr hoch. Ich werde also einen grünen Rand von wenigen Pixeln um mich herum haben.
Der Greenscreen kann bei entsprechender Höhe nicht breit genug werden

Figure 2. Nicht viel Platz unterm Dach

Was wird gebraucht

Für mich persönlich fällt in diesem Szenario ein gekaufter Greenscreen flach. Selbstmachen und hoffen war angesagt :)

Dafür habe ich mich umgesehen und bin bei IKEA fündig geworden. Hier die Einkaufsliste (Keine Affiliate Links):

Gesamtkosten: ca. 21 €

Zur Erklärung: Der Garderobenständer Rigga passte von der Breite perfekt in mein Dachgeschoss und ist zusätzlich höhenverstellbar. Die Breite ist jedoch ein Problem, auf das ich später noch näher eingehen werde. Bei der Decke war klar, dass sie sehr lichtdurchlässig ist. Deswegen bin ich auf Nummer sicher gegangen und habe zwei Exemplare bestellt. Das hat sich als gute Idee herausgestellt!

Zusammenbau

Den Garderobenständer zusammenzuschrauben ist mit handwerklichen Geschick möglich. Die Deckenbefestigung an ihm ein klein wenig hakelig da beides sehr glatt ist. Es empfiehlt sich zuerst eine Decke zu befestigen und dann die zweite. Ich habe das pragmatisch gelöst - nicht unbedingt hübsch (siehe Bild)

Figure 3. Befestigung der Decken mit Wäscheklammern am Garderobenständer

Das Setup

Der Greenscreen ist jetzt schon bereit, um ihn hinter mir zu platzieren. Aufgrund der Gegebenheiten steht er so nah bei mir, dass er am Stuhl anliegt.

Figure 4. Greenscreensetup direkt hinter Stuhl

Verwendung in Videokonferenzsoftware (Mit virtueller Kamera aus OBS Studio)

Viele Videokonferenzprogramme bieten die Möglichkeit, Hintergrundbilder einzublenden. Meistens wird der Sprecher anhand eines Algorithmus erkannt. Das ist dann je nach Bildhintergrund, den die Kamera aufnimmt, nicht perfekt. Arme verschwinden, Artefakte entstehen um den Kopf und um Gliedmaßen und Durchscheinen des Zimmers sind hier Standard.

Am Beispiel von Microsoft Teams zeige ich das Ergebnis, wenn stattdessen ein Greenscreen verwendet wird und mit OBS Studio eine virtuelle Kamera in Teams eingebunden wird. Mit ihr, habe ich auch die Breite so zugeschnitten, dass keine Ränder zu sehen sind. (Teaser: Wie das eingerichtet wird, beschreibe ich in einem weiteren Beitrag).

Figure 5. Endergebnis in Microsoft Teams mit virtueller Kamera aus OBS Studio

Streulicht und Beleuchtung

Für das oben erreichte Ergebnis wurden noch ein paar Vorkehrungen getroffen, um den Greenscreen gleichmäßiger auszuleuchten. Je gleichmäßiger er ausgeleuchtet ist, desto besser!

Alle Türen schließen
Alle Rolläden herunter
Vorhänge schließen
Optional: Softboxen (hier reichen billige; Meine haben 50 € gekostet)

Greenspill

Leider lässt sich mit meinem Setup der Greenspill nicht vermeiden. Der Greenscreen ist einfach zu nahe an mir dran.

Figure 6. An der Hand ist der Greenspill deutlich zu erkennen

Was geht noch?

In einem weiteren Beitrag werde ich das Tool OBS Studio vorstellen und zeigen, dass der Greenscreen wunderbar für Livecoding, Konferenzen und Workshops eingesetzt werden kann.

Bis bald!

Build your own Webcam - Part 2

Sat, 16 May 2020 00:00:00 +0000

As promised, I gave some of the tutorials from my last post a try.
Here is what I learned so far.

Video Source

Android

For android based devices, it seems that IP-Webcam is quite a good choice.
The website looks quite basic but the software itself works great and provides lots of options!
When you start it on your phone, the phone will spin up a webserver which you then can connect to with any other device on your network (make sure that it is only accessible from your trusted network!)
and it gives you lots of options.

It also comes with a simple driver for this IP based webcam for your PC.

Raspberry Pi

Since I had a Raspberry Pi Zero and a camera lying around, I thought it would be fun to turn it into a webcam.
It was quite clear from the start that the Pi Zero does not have too much power but I thought it is ok to give it a try.

To cut the long story short, here is what I learned:

network connection
you can connect the Pi Zero over WiFi or through a usb based network connection (the pi plays the role of a network adapter which only works with the zero or pi 4)
the usb connection has less lag and more throughput than the WiFi connection
the throughput is still the bottleneck for high-quality, high frame-rate video
mjpg-streamer is a powerful tool to turn your pi into a network camera! It also comes with a cool web interface

lighting - since I wanted to capture the image of some scribbles on paper with this camera, I wanted to have good illumination. So, I remembered that I have an ultra-bright LED display for the pi zero. These LEDs have a very cold light and I didn't manage to set up the white balance to compensate for that.

Result: it was fun to play around with the Pi, but it is not a solution :-)

Software needed on the PC

ManyCam

ManyCam seems to be a nice and easy to use solution with many options and effects.
But it also comes with a price tag.
The pricing plan I would go for is the lifetime studio version for which the price is $119. :-o

ManyCam not just provides a virtual cam for IP based sources, it can also bring together a bunch of other sources, present them as picture in picture, lets you switch through scenes and even lets you add a timer or other effects.
So, if you are willing to pay the price, this tools seems to be quite fun!

SplitCam

SplitCam does not provide as many features as ManyCam and it also didn't look too trustworthy.
When I read the first blog post "How to add StripChat Stream", I knew that I am not the target group :-)

I didn't try the other tools mentioned in the tutorials, because I had another idea:

OBS Studio

OBS Studio is an open source and free tool which I already use to record my talks.

There is a virtual camera plugin for OBS which lets you select the OBS output as webcam input in most video chat solutions.
This allows me to take some input and re-use it as webcam!

I also found out that it supports a VLC video source as input.
This works in such a way that OBS uses the VLC libraries to display a network stream like VLC - VLC itself does not have to be running.
Unfortunately, this turns out to be quite laggy and thus unusable in a live environment.

OBS Ninja to the rescue

As reaction to my last post, Daniel Pisanu mentioned obs.ninja as a solution.
It is really cool, but I needed some help to get it up and running.
This was basically because I didn't understand the solution at first.

The website builds up a video chat connection between any two webRTC capable devices.
As result, you will get a peer-to-peer video stream in your browser.
It works quite like jitsi.

First, I tried to get the room functionality to work and didn't succeed, but if you use the big "Create Reusable Invite" button, it works like a charm.

You can even share your desktop this way.

Since it is browser based, you can add nearly every WiFi connected device as video source.
Even those cheap Amazon kindle fire tablets!

Now, the next step is to add this stream to your OBS scene.
To do so, add a web-browser as source and point it to your OBS-Ninja link.
As a result, you will get a high quality stream with only a tiny lag within OBS!

And this works for other web based resources too!
It even turns out that you can use the stream URL of your raspberry pi cam to workouround the laggy VLC input.
Or add a nice timer through timer.digital-wachsen.de

So, OBS is the way to go for me now!

What about the digital cameras?

I also went through my box of old digital cameras and it turned out that none of it had web cam features.

But yesterday I saw that you can get a Canon EOS 2000D for as cheap as 299€ and I read that the Cannon webcam utility should work with that camera.
So, I ordered it and will see....

Update: I've got my EOS camera and it works well. You have to learn how to handle it (sometimes it does not recognize the camera because it seems to be blocked from another session or the EOS utility - exit it before you use the EOS as webcam). But the result is a sharp and high quality picture!

Conclusion

For me as techhie, OBS is the way to go, but it is not a solution for everyone.

OBS.ninja is a great solution for remote sources.

Regarding the webcam hardware, I am quite happy with the quality of my logitec C920, but I am also eager to try the Canon EOS as new high quality webcam.

Build your own Webcam

Fri, 1 May 2020 00:00:00 +0000

Before Corona, I was quite happy with my build-in webcam together with an additional external logitec C920HD.
The logitec mainly replaced my build-in cam for my company notebook - it has a far better quality.

But now, that I am forced to do everything online, two webcams are not enough.
The logitech is now mounted above some sheets of paper as a replacement for a whiteboard.
For the online piano lessons of my son, I need two additioanal webcams with a special setup.

So, I need more webcams than I currently have but no additional webcams are available through online stores :-(

Time to re-think the solution!

Old Smartphones as webcam

Golem.de created a good (german) article about solutions which use smartphones as webcams.

TL;DR: EpocCam, DroidCam and ManyCam are the proposed solutions.

Raspberry Pi as webcam

Another interesting solution is to utilize one of those many raspberries I bought and never used.

Google provides tutorials for this solution:

Both tutorials are a bit different but both use the raspberry as network based camera.
This means it is the same approach as with the smartphone.

For me, the main question now is, if there is a PC software / driver which is capable to use both - the smartphone and the raspberry - as a webcam.

When your Raspberry is set up and ready to go, you will find more ideas to play around with it in the official camra guide - great ressource!

Stay tuned because I will soon write about my experience...

Update: @phaus mentioned on twitter that Canon is updating their cameras to double as webcam.
Maybe I should check my old cameras to see if I could use them as webcams, too!

How to Self-Record your Conference Talk

Mon, 9 Mar 2020 00:00:00 +0000

Some time ago, I attended a talk by Bernd Rücker.
I can't remember the talk anymore (probably something about workflows and decisions),
but I remember that he set up a camera and self-recorded his talk.
After the talk, he used the coffee break to post-process the video and upload it to youtube.

He has written a short blog on how he records his talks and so I started my journey.

Here is my experience so far...

I started with Camtasia because I got a cheap copy through Humble Bundle (since I do this as a hobby, my decisions are quite price-sensitive).
But I am not quite happy with Camtasia for recording since it draws quite a lot of CPU power.
It sometimes slows my machine down to the point where you can see characters slowly pop up while I type.
Not good.

So I searched for another recording tool and found Open Broadcaster Software (OBS).
This tool is optimized for gamers who want to stream their gaming experience live to twitch and other channels.
This implies that it does not draw too much CPU resources.

It also works quite nicely to record your various video and audio sources.
The main drawback is that it is not very intuitive to use, so here are some tips and tricks:

record multiple video sources

OBS does not record multiple video sources to multiple files.
It only records one video with multiple sources layed out.
This allows you to record your main presentation screen (the projector) and overlay the speaker video as a small webcam video on top of it.

However, this way you have to first decide about the layout of your video.
The decision will be final.
I wanted to have more freedom, so I found the following trick:

Create a canvas which is big enough to place all your source on it and record them side by side.
This allows you to record all video sources in one file and separate the sources later.

The following video shows this concept:

record multiple audio sources

I thought it was enough to record one audio source - my speaker microphone (see below for details), but I was wrong.
The last time I tried to record my talk, I only noticed afterward that I recorded the wrong audio source.
This turned the whole recording to be worthless.

So I searched for a solution on how to record all available microphone - webcam, speaker-mic and build in.
Just to be sure.

The solution is to first choose an output format that is capable to record multiple audio channels.
The details are explained in the following video:

set up all sources

One day I tried to set up my recording upfront but I wasn't able to set up the speaker screen but OBS didn't who me the second screen as a source.
This was when I found out that it only shows sources which are already connected to your notebook.

The next time, I knew that I had the perfect setup from two days before and I relied on this setup in another location.
Unfortunately, the setup was created with a low-res projector in the first location and the second location had a high-res projector.
So I only recorded the upper left quarter of the screen :-(.

OBS seems also to have problems when you disconnect and then reconnect devices (USB webcam).
Even when I just close my notebook and re-open it, the internal webcam does not work as a source anymore and I have to re-setup it.

So, here is my tip: when it is your turn, try to be at the location 15 minutes before and setup OBS individually for the location and leave your notebook up and running.
You might even want to already start your recording in order not to forget it when your talk starts.

Hardware

Camera

As a camera, I use the same Logitech HD 920 pro as Bernd.

It has a great video quality and the microphones record a full room.
So if your speaker mic has problems, the webcam mics are a good fall back.

A cheap camera stand (like the one mentioned by Bernd) is enough to mount it in most situations and it is easy to carry.

Microphone

A cheap lavalier or lapel microphone for ~10€ is a great choice to record your voice.
I will only record your voice and not the whole room as the webcam does.
And in most situations, you don't need a wireless mic.
The cable of these cheap mics is long enough to give you some freedom to move a bit behind your notebook and they are just far cheaper than wireless mics.

You could also use a bluetooth headset, but the sound quality is not as good since the loudspeaker and mic share the frequency band over one bluetooth connection.

Presenter

When you are used to a laser pointer as a presenter, keep in mind that the laser pinter will not be recorded through your screen recording.
And the quality of your camera will not be good enough to capture the projected screen.
Even with a decent camera, the camera has to cope with the light conditions.

That's why I use a Logitech Spotlight as presenter:

Not cheap but super cool!

Post-Processing

OBS helps you to record your talk but it will not do any post-processing.
That's where Camtasia shines.
It is a simple tool to cut, edit and re-render your final video.
It also does the trick to import your recorded video (screen + webcam) twice and clip it to separate the two sources.

Other Tips & Tricks

When I started, someone told me that I could record different sources with different devices.
"Just clap your hand at the start of your recording and it will be easy to synchronize the sources."

So I recorded my voice with my mobile phone (yes, freedom to move around!) and video with an action cam.

Yes, you will easily find your hand-clap in the video and audio channel, but it turned out that the different sources diverged some minutes(!) after a one hour talk.
That's why I only record with one device - my speaker notebook - since then.

Hope this blog might help you with your own recordings!

Präsentationen Best Practices

Sat, 27 Jul 2019 00:00:00 +0000

Manchen Sprechern hört man einfach gerne zu und bei anderen möchte man trotz eines interessanten Themas einfach nur den Raum verlassen. Viele Dinge beim Vortragen kommen mit der Zeit. Darunter fällt für mich die nötige Gelassenheit, eine klarere Ausdrucksweise und ein gewisser Witz. Diese Dinge können aus meiner Erfahrung die wenigstens Sprecher, die noch nicht lange vor Publikum sprechen. Das sieht man eher bei erfahrenen Sprechern mit mehreren Jahren Erfahrung.

In den letzten beiden Jahren war ich auf vielen Konferenzen und habe sehr viele gute Vorträge angehört. Mit der Zeit kristallisiert sich ein Muster heraus, welche Eigenschaften ein guter Vortrag haben muss. Dabei nehme ich den Sprecher erst einmal aus der Gleichung und fokussiere mich auf das Foliendesign, Dinge die Sprecher unbedingt tun sollten unabhängig vom persönlichen Stil und die Struktur eines einprägsamen Vortrags.

Foliendesign

Die Folien sind nicht der Mittelpunkt der Präsentation. Dieser Punkt kann nicht oft genug wiederholt werden. Die Folien sind nicht der Mittelpunkt der Präsentation.

Nachdem das aus der Welt geschafft ist: Folien sind wichtig. Sie sollten den Sprecher aber nur unterstützen und dem Publikum einen Anhaltspunkt darüber geben, über was gerade gesprochen wird. Der größte Teil der Informationen sollte der Sprecher liefern. Sonst wäre er überflüssig.

Ein sehr gutes Beispiel für minimalistische Folien gibt es von Daniel Rietmüller: Clean Code erfolgreich einführen

Wem das Design des obigen Vortrags etwas zu minimalistisch ist, der kann sich auch ein anderes Farbschema aussuchen. Bei codeaffinen Sprechern ist reveal.js gerade sehr beliebt. Jedes einzelne Farbschema ist auf maximale Lesbarkeit ausgelegt und kann durch HTML/CSS/JavaScript eigenhändig erweitert werden.

Zum Abschluss dieses Punktes noch ein gutes Video, in dem die Wirkung von schlechten Folien humorvoll demonstriert wird:

Vortrag

Zum Vortrag selbst gibt es ein paar sinnvolle Tricks, die helfen eine Verbindung zum Publikum aufzubauen. Denn die eigentliche Aufgabe eines Sprechers, ist es ein persönliches Gespräch mit seinem Publikum zu führen und dadurch eine Idee oder Wissen zu vermitteln.

Die Besten schaffen es tatsächlich, dass ich mich direkt angesprochen fühle. Dadurch kommt die Botschaft besser an. Aus meiner Erfahrung als Vortragender waren die Situationen in denen ich am meisten positives Feedback bekommen habe, die in denen ich mich eins mit dem Publikum gefühlt habe (obwohl der Vortrag inhaltliche Mängel hatte ;) ).

Es gibt aus meiner Sicht zwei Kernpunkte, die berücksichtigt werden sollten. Erstens spricht ein guter Sprecher mit jedem einzelnen des Publikums. Dazu ist es wichtig, Augenkontakt aufzubauen und diesen für mindestens einen Gedankengang zu behalten. Dann bekommt der Zuhörer das Gefühl, dass er direkt angesprochen wurde. Eine Mikrokonversation also. Wer es als Sprecher einmal bewusst probiert hat, wird erstaunt sein, wie gut das funktioniert.

Es gibt nur ein Problem. Wie geht man bei großen Räumen vor? Das ist relativ einfach zu bewerkstelligen: Der Raum wird in Sektoren eingeteilt und nacheinander mit der oben beschriebenen Technik abgearbeitet.

Natürlich ist so ein Vorgehen nur möglich, wenn der Vortrag sitzt, was mich zum zweiten Kernpunkt bringt. Ein guter Vortragender weiß, was er vermitteln will. Er kann seinen Vortrag durch mindestens fünfmaliges Üben so gut, dass er dem roten Faden folgen kann ohne nachzudenken. Das verschafft die Freiheit, die gebraucht wird, um die persönliche Verbindung zum Publikum herzustellen!

Der rote Faden

Es gibt viele Möglichkeiten eine Vortrag aufzubauen, über die ich in einem späteren Blog noch schreiben werde. Wichtig bei allen ist ein erkannbarer roter Faden, um den es sich drehen sollte. Das heißt, dass der Bezug zum Grundthema für den Zuhörer erkennbar bleiben sollte. Dabei ist das Abtauchen in etwas weiter entfernte Gedankengänge vollkommen in Ordnung. Es sollte nur vorher gesagt werden, warum das passiert oder in einem AHA-Moment enden, der dem fragenden Publikum eine überraschende Einsicht präsentiert. Letzteres habe ich bis jetzt selten erlebt. Uwe Friedrichsen

Sehr heikel sind in diesem Zusammenhang auch Live-Demos, bei denen mehrere Programme gleichzeitig geöffnet werden. Das Springen zwischen den Fenstern verwirrt oft. IDEs sind meistens an sich schon komplex. Auf der Leinwand alles so schnell zu erfassen, ist als Zuschauer fast unmöglich. Hier ist eine genaue Erläuterung des Vorgehens und aller relevanten Bestandteile wichtig. Hier hilft es ungemein besonders langsam vorzugehen und die Reaktionen des Publikums zu beobachten!

Fazit

Mit einfachen Mitteln, die nichts mit dem persönlichen Stil zu tun haben lässt sich bei Vorträgen viel erreichen. Achtet man bei der Erstellung der Folien auf ein klares minimalistisches Design und stellt den Sprecher in den Vordergrund ist der Grundstein gelegt. Wird dann noch eine persönliche Verbindung mit dem Publikum hergestellt kann die gut eingeübte und mit einem roten Faden durchzogene Präsentation nur gelingen!

Die Präsentation von Kevin Goldsmith ist ein Beispiel für alle Punkte, die ich aufgeführt habe:

Quellen: http://amzn.to/2xPUpBF

Mutationstesten: Abgrenzung zu anderen Testverfahren

Sat, 27 Jul 2019 00:00:00 +0000

Mutationstesten ist ein Verfahren, um Tests aussagekräftiger zu machen. Es ist quasi der Goldstandard unter den Testabdeckungsmetriken. Warum? Es prüft nicht nur, ob eine Zeile Code abgedeckt wurde, sondern auch, ob der/die dazugehörige(n) Test(s) tatsächlich Fehler in dieser Zeile finden können. Dazu werden kleine absichtlich kleine Fehler in den Code eingebaut (Mutationen), die von der Testsuite gefunden werden sollten. Wie das alles genau aussieht, werde ich demnächst beschreiben.

Heute geht es mehr um die Platzierung von Mutationstesten im Vergleich zu anderen Testverfahren, wie zum Beispiel Unit-Tests.

Was Mutationstests nicht sind

Mutationstesten testet nicht den eigenen Sourcecode, sondern die dazugehörige Testsuite. In meinen beiden Vorträgen über Mutationstesten habe ich das nicht genau genug herausgearbeitet. Das hat Gründe, auf die ich in den nächsten Abschnitten eingehen werde.

Die Tests testen?

Um die Tests zu testen braucht es eine Grundvoraussetzung: Testabdeckung bzw. Testüberdeckung. Im Falle von Mutationstesten reicht hier die sehr einfache Metrik der Zeilenüberdeckung aus, die besagt, dass die Tests dazu geführt haben, dass eine Zeile ausgeführt wurde. Erst wenn eine Zeile von mindestens einem Test ausgeführt wurde, wird sie für Mutationen in Betracht gezogen. Ansonsten würden die Mutationen mit Sicherheit nicht von der Testsuite entdeckt werden. Dementsprechend ist die Zeilenüberdeckung mit Mutationstesten quasi verheiratet, damit sie effektiv durchgeführt werden kann. Ansonsten würde man viele nicht auffindbare Mutationen erzeugen.

Man kann Mutationstesten also als eine Art Regressionstest beschreiben, das sicherstellt, dass eingebrachte Fehler in den Code von der Testsuite gefunden werden können. Es ersetzt also nicht den klassischen Unit-Test oder macht andere Testverfahren überflüssig. Viel eher ist es eine praktikable Hilfestellung, um die Qualität der Testsuite hochzuhalten.

False Positives

Ich spreche in meinem Vortrag gerne von False Positives. Technisch ist dieser Begriff bestimmt nicht 100 % korrekt (Siehe hier für eine sinnvolle Erklärung). Aber er beschreibt für mich den Fall, dass mein Tool ein Problem meldet, wo eigentlich keines ist. Darunter fallen:

Redundanter Code, der nichts zu Funktionalität beiträgt
Mutationen die nicht von der Testsuite gefunden werden, aber die Funktionalität nicht einschränken

Durch die Einführung von Mutationen fallen solche Codestellen auf (durch nicht getötete Mutationen). Bei genauerer Inspektion stellt sich dann aber heraus, dass man die entsprechenden Codezeilen entweder löschen oder eben ignorieren kann.

Was man nebenbei so findet…

Sehr oft werden auch Mutationen nicht getötet, wenn sie auf von mir sogenannte subtile Bugs hinweisen. Der Aufruf von einer Methode ohne Rückgabewert (void) aber mit Seiteneffekt ist so ein Fall. Meine Testsuite muss in diesem Fall erheblichen Zusatzaufwand betreiben (zum Beispiel mit Mocks/zusätzlichen Datenbankzugriffen), um diesen Seiteneffekt sinnvoll zu testen. Das weist für mich auf einen möglichen Designfehler hin.

Ein weiteres Beispiel dafür sind if-Abfragen, deren Rumpf einen Seiteneffekt erzeugt. Hier kann durch Unachtsamkeit leicht ein Bug eingebaut werden. Mit Mutationstesten findet man diese Stellen zielsicher und sie sollten dann nicht einfach mit einem zusätzlichen Test vor dem Unglück bewahrt werden. Besser ist es ein Refactoring zu machen. Entweder durch explizites Ausschreiben der Bedingung oder zum Beispiel durch die Auslagerung in eine eigene Methode.

Fazit

Mutationstesten härtet die eigene Testsuite auf effektive Weise. Nebenbei findet sich dabei auch noch die ein oder andere Stelle im getesteten Code, der ein Refactoring gut tun würde.

Die Probleme mit DRY auf Modulebene

Sat, 27 Jul 2019 00:00:00 +0000

Das DRY – Don’t Repeat Yourself – Prinzip haben die meisten Entwickler*innen als wichtiges Prinzip verinnerlicht.

Um das nüchtern festzustellen: Das Kopieren von Code an sich ist im ersten Moment schmerzlos und geht schnell. Entwickler*innen müssen sich keine Gedanken über eine sinnvolle Abstraktion oder den Ort des Codes machen, sondern kopieren ihn sich einfach an die benötigte Stelle.

Problematisch ist das erst im Fehlerfall. Tritt ein Fehler in einem Codestück auf, das x-Mal dupliziert wurde, dann ist er in allen Duplikaten ebenfalls zu beheben. Meistens wird dann eines davon vergessen und schon fängt man sich den gleichen Fehler an einer anderen Stelle erneut ein. Das ist für alle Beteiligten frustrierend.

Die pragmatische Lösung: Ein gemeinsames Modul

Als Lösung bietet sich ein gemeinsames Modul an: Nennen wir es der Einfachheit halber base. Dort kommt die sogenannte Basisfunktionalität hinein, die jede Applikation braucht. Problem gelöst, wir können effizient arbeiten.

An der Umsetzung hapert es

Die Idee eines Basismoduls base klingt in der Theorie einleuchtend und für mich ist sie auch eine adäquate Lösung. Wäre da nicht das Problem der Umsetzung. Hier gibt es mehrere Punkte, die base zum Scheitern verurteilen.

Was ist Basisfunktionalität

Bei einer steigenden Anzahl von Basisfunktionalitäten wird es für den einzelnen Entwickler immer schwieriger zu entscheiden, welche Funktionaliät denn eigentlich in base untergebracht werden soll. Gepaart mit Zeitdruck wird base immer weiter aufgebläht. Zwangsläufig importiert damit jede davon abhängige Applikation Funktionalität die sie nicht braucht!

Nehmen wir als Beispiel an in base befindet sich eine Utility-Klasse, die für String-Manipulationen zuständig ist. Als weitere Funktionalität gibt es ein ganzes Package, dass das Einlesen von CSV-Dateien ermöglicht und ein Package, dass verschiedene Formate exportieren kann.

Braucht jede Applikation die Exportfunktionalität oder das Einlesen von CSV-Dateien? Sicherlich nicht! Aber wenn die Fähigkeiten zur String-Manipulation in base liegen und das Modul deswegen importiert, kriegt man das im Schlepptau mit. Hier besteht eine unnötige Kopplung.

Abhängigkeit führt zu Nicht-Evolvierbarkeit

Spinnen wir das Gedankenspiel noch etwas weiter und fügen noch einige Applikationen hinzu, am besten noch mit unterschiedlichen Java-Versionen. So bekommt man einen schönen Baum mit base als Wurzel.

Benötigt man neue Funktionalität in base, da irgendwer meint sie ist eine Basisfunktionalität, dann muss sich base ändern. Idealerweise erledigt man das auf einem Feature Branch und macht anschließend einen Merge. In der Realität entfällt dieser Merge manchmal und der Branch entwickelt sich autonom weiter. Vielleicht sind auch schon neue Features aus einer höheren Sprachversion ausversehen verwendet worden. Das Ergebnis sind zwei ähnliche base-Varianten, die man nicht mehr Mergen kann.

Ich höre gerade die Zweifler: Das kann doch nicht passieren, wenn man sich an das richtige Vorgehen hält!

Denen gebe ich absolut recht. Zum Beispiel kann man die Java-Version mit Maven festsetzen oder vor der Auslieferung einen Merge auf master fordern, keine Frage. Aber wie oft steht man unter Zeitdruck, oder die Tools versagen und dann ist es doch passiert? Und ist es in Produktion, dann muss man plötzlich doch eine Kopie pflegen, inklusive aller Bugs, die sich darin verstecken :( .

Mehrere Utility-Module

Die Lösung der oben beschriebenen Probleme liegt in der Zerlegung von base in spezialisierte Module. So kann jede Applikation selbst entscheiden, welche Basisfunktionalität sie wirklich braucht.

Ob man das so weit treiben will, wie bei node.js und left-pad lasse ich mal dahingestellt. Ich bin aber durchaus für die Linux-Philosophie Do one thing and do it well.

Es gibt einfach keinen Grund in seinem Modul unnötigen Code mitzuschleppen. Dieser trägt im besten Fall dazu bei, dass das API des Moduls schwieriger zu verstehen ist, da es zu viele Belange abdeckt. Im schlechtesten Fall führt es dazu, dass man Applikationen neu ausliefern muss, da genau dieser Code einen kritischen Bug (Sicherheitslücken!) aufweist und deswegen gepatcht werden muss.

Hier kann man schön einen Kreis zum Single Responsibility Prinzip (SRP) ziehen. Nach diesem soll es nur einen Grund geben dürfen, damit sich eine Klasse ändert. Überträgt man dieses Prinzip auf die Modulebene, dann landet man zwangsläufig bei kleinen spezialisierten Modulen.

Fazit

Ein gemeinsames base-Modul ist in der Theorie eine pragmatische Lösung, um Basisfunktionalität an einem zentralen Ort zu pflegen. In der Praxis führt es aber eher zu einem aufgeblähtem Modul, dass als Sammelbecken für alles Mögliche herhalten muss. Durch ungewolltes Kopieren der Codebase, zum Beispiel mit einem nicht gemergten Feature Branch, holt man sich viele Probleme ins Boot. Vor allem Codeduplikation inklusive aller Bugs und Updatezwang aller Applikationen bei kritischen Bugs.

Wesentlich sinnvoller ist eine Aufteilung der Basisfunktionalität in spezialisiertere Module. Applikationen können sich gezielt davon bedienen und die Module wachsen nicht unkontrolliert an. Die Wahrscheinlichkeit für Codeduplikation sinkt.

Das Ziel von Mutationstesten

Sat, 27 Jul 2019 00:00:00 +0000

Mit das Interessanteste an einem Vortrag sind die anschließenden Fragen. Beim letzten Mal hatte ich das Gefühl die Fragen zum Mutationstesten nicht zufriedenstellend beantwortet zu haben. Deswegen versuche ich das, in den nächsten Blogs nachzuholen.

Die ersten beiden Fragen waren:

Kann durch eine Mutation nicht etwas Gutes entstehen?
Was passiert, wenn sich zwei Mutationen gegenseitig ausschalten?

Gutes durch Mutationen?

Mutationstesten führt Änderungen in den Sourcecode ein, die syntaktisch korrekt sind. Diese Änderungen verändern jedoch die Semantik der Codebasis auf jeweils kleine Weise. Danach wird für jede einzelne Mutante überprüft, ob ein Test die Änderung bemerkt. Die Tests dienen praktisch als Spezifikation, wie sich die Codebasis verhalten soll. Eine Abweichung davon ist meiner Meinung nach immer eine Regression und damit als Fehler einzustufen.

Im besten Fall kann eine Mutante also nur dazu führen, dass kein Test fehlschlägt. Ob das gut oder schlecht ist, lässt sich nur durch eine genaue Betrachtung herausfinden. Es gibt dabei zwei Möglichkeiten. Die Mutante ist tatsächlich gutmütig und führt nicht zu falschem Programmverhalten. Das tritt tatsächlich auf, was ich in der Livedemo meines Vortrages immer zeige. (Workspace dazu gibt es auf github)

Schlägt kein Test fehl, dann kann das auch heißen, dass meine Testsuite für diese Mutation blind ist. Das ist aus meiner Sicht der Normalfall und sollte deshalb behoben werden.

Ansonsten schlägt ein Test fehl und der Sourcecode verhält sich an dieser Stelle nicht wie von den Tests gefordert. Das würde ich als definitiven Fehler einstufen.

Durch Mutationen kann nichts Gutes entstehen! Sie können nur gutmütig, also nicht Semantik verändernd sein!

Gegenseitiges Ausschalten

Können sich zwei Mutationen gegenseitig ausschalten? So wie zwei Fehler sich gegenseitig aufheben können?

An dieser Stelle kommt ein Nein. Die Frage kam auf, da ich im Pecha Kucha Vortrag nicht genug Zeit und Präzision hatte, den genauen Ablauf eines Mutationstests zu verdeutlichen. Ich hole das hiermit nach:

Zuerst werden Mutanten aus dem Sourcecode erstellt
Jede Mutante enthält eine einzige Veränderung, der restliche Sourcecode wird nicht verändert
Jede einzelne Mutante enthält den gesamten Sourcecode (Es handelt sich also um eine Kopie mit der einen Änderung)
Alle Tests werden auf jeder einzelnen Mutante ausgeführt
Schlägt mindestens ein Test fehl bei einer Mutante, dann gilt sie als getötet

Rein vom Ablauf her ist es also nicht möglich, dass sich Mutanten gegenseitig aufheben.

Fazit

Mutationstesten so zu erklären, dass das Vorgehen verständlich ist, ist schwierig. Durch diesen Beitrag habe ich gezeigt, dass aus Mutationen im besten Fall nichts Schlechtes entstehen kann. Außerdem wurde erklärt, dass sich Mutanten, aufgrund des Ablaufs des Mutationstestens, nicht gegenseitig aufheben können.

In den nächsten Beiträgen mache ich zuerst einen Ausflug in Überdeckungsmaße. Die Frage die ich abschließend klären will lautet: Führt eine hohe Abdeckung bei diesen Maßen bereits zu einer deutlich besseren Mutationsabdeckung.

Code Coverage am Beispiel Zweigüberdeckungs Branch Coverage

Sat, 27 Jul 2019 00:00:00 +0000

Im letzten Blog ging es um Zeilenüberdeckung.

Ich habe gezeigt, wie man sie am Beispiel des Game of Life von Conway einsetzt, um bessere Tests zu schreiben, die jede Anweisung mindestens einmal ausführen.

In diesem Teil möchte ich zuerst zeigen, warum die Zeilenüberdeckung zwar eine sinnvolle Metrik ist, aber doch nicht ausreicht, um die Qualität der Testsuite abzusichern. Das lässt sich sehr leicht an einem Fehler zeigen, den die bisherigen Tests nicht gefunden haben.

Als Zweites möchte ich auf die Zweigüberdeckung eingehen. Diese ist eine echte Obermenge der Zeilenüberdeckung und umfasst die Zeilenüberdeckung damit vollständig. Darüber hinaus wird mit einer vollständigen Zweigüberdeckung erreicht, dass jeder mögliche Zweig bei der Ausführung einer Codebasis von den Tests mindestens einmal durchlaufen wird.

Zeilenüberdeckung unzureichend

Die bis jetzt implementierte Testsuite aus dem letzten Blog hat eine Zeilenüberdekcung von 100% erreicht. Dieser Wert täuscht darüber hinweg, dass die Testsuite nicht ausreichend ist.

Betrachten wir den Konstruktor genauer:

public Cell(int neighborCount) {
  neighbors = new Cell[neighborCount];
}

Hier versteckt sich eine java.lang.NegativeArraySizeException. Sie tritt auf, wenn ein negativer Integer übergeben wird.

Das ein solcher Fehler nicht von der Testsuite abgedeckt wird, ist nicht verwunderlich. Aus eigener Erfahrung weiß ich, dass man Tests gerne für den positiven Fall schreibt. Der negative Fall wird aus Unachtsamkeit oder Faulheit weggelassen.

Zweigüberdeckung: Verschärfte Zeilenüberdeckung

Die Zweigüberdeckung fordert, dass ein Zweig der Codebasis mindestens einmal durchlaufen wird. Damit subsumiert sie die Zeilenüberdeckung und ist ein leistungsfähigeres Maß. Eine Testsuite mit vollständiger Zweigüberdeckung stellt sicher, dass jeder Zweig der Codebasis einmal durchlaufen wurde. Gibt es keine Bedingungen oder Schleifen, dann entspricht sie praktisch der Zeilenüberdeckung.

Bei Bedingungen müssen die Tests sicherstellen, dass der Wert der Bedingung einmal true und einmal false wird. Ebenso bei Schleifen. Was zur Folge hat, dass die Schleife nicht mehr als zweimal durchlaufen werden muss, um die Zweigüberdeckung zu garantieren.

Gibt es jedoch komplexere Abhängigkeiten im Programmablauf, dann können Sie ungetestet bleiben. Wie das genau aussieht, zeige ich an der Methode isAliveInNextGeneration() der Klasse Cell. Hier ist sie noch einmal:

public boolean isAliveInNextGeneration() {
  int livingNeighbors = 0;
  for (Cell cell : neighbors) {
    if (cell.isAlive()) {
      livingNeighbors++;
    }
  }

  if (!isAlive &amp;&amp; livingNeighbors == 3) {
    return true;
  }
  else if (isAlive &amp;&amp; livingNeighbors &lt;= 3) {
    return true;
  }

  return false;
}

Unsere Testsuite erreicht für die Zweigüberdeckung folgendes Ergebnis:

link:http://johannesdienst.net/wp-content/uploads/2017/08/BranchCoverage_isAliveNextGeneration_initial.png"><img src="http://johannesdienst.net/wp-content/uploads/2017/08/BranchCoverage_isAliveNextGeneration_initial.png" alt="BranchCoverage_isAliveNextGeneration_initial" width="1051" height="704" class="aligncenter size-full wp-image-887" />]

In Zeile 27 und 28 wurden jeweils beide Branches durchlaufen. Da liegt daran, dass wir in den Tests ein Cell-Array mit lebenden und nicht lebenden Cell-Objekten übergeben haben.

Interessanter wird es da in Zeile 33. Nur einer von vier Branches wurde abgedeckt. Selbiges in Zeile 36. Reduzieren wir !isAlive und livingNeighbors == 3 der ersten Bedingung auf zwei Booleans, dann ergibt sich eine Wahrheitstabelle:

!isAlive

livingNeighbors == 3

----------

--------------------

true

false

true

Die Fälle 1, 3 und 4 sind bereits durch die Testsuite abgedeckt. Für den zweiten Fall soll die Testsuite um einen Test erweitert werden. Eine tote Zelle mit sieben lebenden Nachbarn ist in der nächsten Generation immer noch tot:

@Test
public void setSevenLivingNeighbors_IsDead_IsDeadInNextGeneration() {
  Cell cell = getCell(false, 8);
  Cell[] neighbors = new Cell[8];
  for (int i = 0; i &lt; 8; i++) {
    if (i &lt; 7) {
      neighbors[i] = getCell(true, 8);
    }
    else {
      neighbors[i] = getCell(false, 8);
    }
  }
  cell.setNeighbors(neighbors);
  assertFalse("Cell should be dead with seven living neighbors", cell.isAliveInNextGeneration());
}

Mit diesem Test ergibt die Zweigabdeckung:

Interessanterweise führt dieser eine Test dazu, dass auch in Zeile 36 die Zweigüberdeckung vollständig ist. Das liegt an den Bedingungen selbst. Die Wahrheitstabellen bestätigen dies. Das Aufstellen überlasse ich aber dem geneigten Leser :-)

Der ergänzte Test ist meiner Meinung nach wichtig, da er einen negativen Fall abdeckt, der in der ursprünglichen Testsuite gefehlt hat.

Fazit

Die Zeilenüberdeckung findet nicht unbedingt Fehler. Sind die Tests nicht sinnvoll geschrieben oder decken nur den Positivfall ab, dann läuft man Gefahr sich in falscher Sicherheit zu wiegen.

Auch eine vollständige Zweigüberdeckung hilft an dieser Stelle nicht weiter. Auch wenn sie als Obermenge der Zeilenüberdeckung noch umfangreichere Tests fordert. Sie fordert aber, dass Bedingungen sowohl mit dem Wert true als auch false durchlaufen werden. Durch sie konnte ein fehlender Test ergänzt werden, der ansonsten nicht getestet worden wäre.

Da sie nur Zweige betrachtet ist sie aber nicht so leistungsfähig wie die Pfadüberdeckung, die alle möglichen Pfade in der Codebasis abdeckt. Um dieses Thema geht es im nächsten Blogpost.

Links: Teil 1 Zeilenüberdeckung Kontrollflussorientierte Testverfahren bei Wikipedia

Code Coverage am Beispiel: Pfadüberdeckung (Path Coverage)

Sat, 27 Jul 2019 00:00:00 +0000

In den letzten beiden Blogposts ging es um die Überdeckungsmaße Zweigüberdeckung Zeilenüberdeckung. Die Zweigüberdeckung ist ein stärkeres Maß für die Qualität der Abdeckung, da sie die Zeilenüberdeckung enthält. Sie ist also eine echte Obermenge.

Die Pfadüberdeckung ist wiederum eine echte Obermenge der Zweigüberdeckung und ist damit als das härteste Maß der Überdeckungsmessung zu betrachten. In diesem Post wird zuerst wieder an einem Beispiel die Pfadüberdeckung vorgestellt. Ziel ist es, eine vollständige Pfadüberdeckung durch die vorhandene Testsuite zu erreichen.

Auf los geht’s los :)

Pfadüberdeckung die Theorie: Vollständig

Die Pfadüberdeckung kommt in mehreren Varianten vor. Zuerst soll jedoch die vollständige Pfadüberdeckung erläutert werden. Nehmen wir uns dazu eine einfache Methode als Beispiel (Achtung: kein sinnvolles Beispiel!):

public int doSomething(int max) { int temp = max;

if (max &lt; 0) {
  return -1;
}

if (max == 0) {
  temp = Integer.MAX_VALUE;
} else {
  return temp;
}

  return temp;
}

Um alle Pfade zu entdecken, lohnt es sich einen sogenannten Kontrollflussgraphen zu erstellen:

Wie man sieht, gibt es selbst in dieser einfachen Methode drei Pfade, die durch separate Tests abgedeckt werden müssen. Überträgt man das auf eine größere Codebasis, dann gibt es eine unendliche Anzahl von Pfaden. Eine vollständige Pfadabdeckung ist also nicht praktisch umsetzbar!

Pfadüberdeckung die Theorie: C2b und C2c → Schleifen begrenzen

Eine Sache, die in der vorherigen Methode bewusst ausgespart wurde, sind Schleifen. Diese führen zu potenziell unendlich vielen Pfaden, da jeder Schleifendurchlauf jeweils als eigener Pfad gezählt werden muss. Kombiniert mit weiteren Anweisungen in der Methode explodiert die Pfadanzahl buchstäblich.

Dafür gibt es die eingeschränkten Methoden der Pfadüberdeckungsmessung C2b und C2c. Bei C2b wird die Anzahl der Schleifendurchläufe auf zwei reduziert. Bei C2c auf eine natürliche Zahl n. Damit bekommt man die ausufernde Anzahl der Pfade in den Griff!

Methode vollständig abdecken

Für die Methode isAliveInNextGeneration() soll nun eine C2b-Abdeckung hergestellt werden. Hier noch einmal die Methode:

public boolean isAliveInNextGeneration() {
  int livingNeighbors = 0;
  for (Cell cell : neighbors) {
    if (cell.isAlive()) {
      livingNeighbors++;
    }
  }

  if (!isAlive &amp;&amp; livingNeighbors == 3) {
    return true;
  }
  else if (isAlive &amp;&amp; livingNeighbors &lt;= 3) {
    return true;
  }

  return false;
}

Der Kontrollflussgraph ist ziemlich komplex:

Bei meiner Zählung bekomme ich folgende Pfadanzahl, wenn ich für die For-Schleife drei Pfade annehme:

Erstes IF Then: 3
Zweites IF Then: 3
Zweites IF Else: 3

Das wären dann neun Testfälle für diese Methode. Meiner Meinung nach ist das noch zu schaffen. Außerdem ist dann wirklich jeder Pfad abgedeckt, den der Programmablauf nehmen kann.

Dieses reale Beispiel zeigt, dass die Pfadüberdeckung sinnvoll ist. Praktikabel ist sie deswegen aber noch lange nicht. Die Explosion der Testfälle ist wahrscheinlich in keinem Projekt akzeptabel.

Noch interessanter ist, dass bei meinen Recherchen zu einem Tool für die Messung der Pfadüberdeckung keines zu finden war. Anscheinend hat dieses Maß keine Praxisrelevanz ;) .

Fazit

Die vollständige Pfadüberdeckung ist bei einfachen Methoden leicht zu erreichen. Bei komplexeren Methoden artet es schnell in viel Arbeit aus. Als Abhilfe können eingeschränkte Versionen der Pfadüberdeckung genutzt werden (C2b oder C2c), die aber ebenfalls viele Testfälle erfordern.

Ein weiteres Problem sind nicht beschreitbare Pfade, da sich die Vorbedingungen nicht in der benötigten Kombination herstellen lassen.

Trotzdem ist es ein nützliches Werkzeug, besonders bei kritischen Pfaden, da eine vollständige Abdeckung aller Programmabläufe sichergestellt ist!

Code Coverage am Beispiel: Zeilenüberdeckung (Line Coverage)

Sat, 27 Jul 2019 00:00:00 +0000

Wie letzte Woche angekündigt, werde ich diese Woche beginnen, die verschiedenen Überdeckungsmaße für Code vorzustellen. Als Beispielprojekt habe ich mir das Game of Life von Conway ausgesucht, was als interessante Übungsaufgabe Einiges an Logik hergibt.

Eine einfache Zelle

Die Regeln für Conways Game of Life sind sehr einfach:

Eine tote Zelle wird in der nächsten Generation belebt, wenn sie genau drei lebende Nachbarzellen hat
Eine lebende Zelle lebt in der nächsten Generation weiter, wenn sie genau drei oder weniger als drei lebende Nachbarzellen besitzt
Eine lebende Zelle stirbt in der nächsten Generation, wenn sie mehr als drei lebende Nachbarn besitzt (Überbevölkerung und so ;-) )

Mit diesen Vorgaben habe ich eine einfach Klasse implementiert. Manche Methoden der Klasse sind zur besseren Testbarkeit eingeführt worden:

package jdienst.basic;

public class Cell {

  private boolean isAlive = false;
  private Cell[] neighbors;

  public Cell(int neighborCount) {
    neighbors = new Cell[neighborCount];
  }

  public boolean isAlive() {
    return isAlive;
  }

  public void enlive() {
    isAlive = true;
  }

  public Cell setNeighbors(Cell[] neighbors) {
    this.neighbors = neighbors;
    return this;
  }

  public boolean isAliveInNextGeneration() {
    int livingNeighbors = 0;
    for (Cell cell : neighbors) {
      if (cell.isAlive()) {
        livingNeighbors++;
      }
    }

    if (!isAlive &amp;&amp; livingNeighbors == 3) {
      return true;
    }
    else if (isAlive &amp;&amp; livingNeighbors &lt;= 3) {
      return true;
    }

    return false;
  }
}

Zeilenüberdeckung/-abdeckung

Das Ganze habe ich testgetrieben entwickelt. Am Ende ist eine Testsuite von vier Tests entstanden, die auf den ersten Blick hinreichend gut aussieht. Leider kann man sich darauf nicht verlassen. Deswegen gibt es die Möglichkeit die Tests mit Testabdeckungsmaßen zu überprüfen.

Das einfachste dieser Maße ist die Zeilenüberdeckung/-abdeckung, sie gibt an, ob eine bestimmte Codezeile überhaupt von den Tests ausgeführt wird. Dieses Verfahren zeigt also an, welche Abschnitte der Codebasis nicht von der Testsuite ausgeführt werden.

Daraus folgt, dass Fehler, die sich in diesen Bereichen verstecken, nicht gefunden werden können. Deswegen sollte als Faustregel als Ziel immer eine Abdeckung zu 100 % stehen. Wenigstens bei Code, der Logik enthält. Eine vollständige Abdeckung in der gesamten Codebasis ist nicht effizient umsetzbar und deswegen unwirtschaftlich.

Testsuite bewerten

An dieser Stelle zeige ich die ersten beiden Tests. Den Rest kann man in meinem Repository auf Github finden. Das Projekt inklusive Konfiguration für alle Tools wurde mit Maven angelegt. Mit mvn clean package site:site löst man das Reporting aus. Unter target/site/project-reports.html kann der Report für die Zeilenüberdeckung angezeigt werden.

Hier nun endlich die Tests:

@Test
public void shouldBeDeadAfterConstruction() {
  Cell cell = new Cell(8);
  assertFalse("Cell is alive. But it should not be alive after construction", cell.isAlive());
}

@Test
public void setThreeLivingNeighbors_IsDead_IsAliveInNextGeneration() {
  Cell cell = getCell(false, 8);
  Cell[] neighbors = new Cell[8];
  for (int i = 0; i &lt; 8; i++) {
     if (i &lt; 3) {
      neighbors[i] = getCell(true, 8);
    }
    else {
      neighbors[i] = getCell(false, 8);
    }
  }
  cell.setNeighbors(neighbors);
  assertTrue("Cell should be alive with three living neighbors", cell.isAliveInNextGeneration());
}

public void setThreeLivingNeighbors_IsAlive_IsAliveNextGeneration() { /* ... */ }

public void setEightLivingNeighbors_IsAlive_IsDeadNextGeneration() { /* ... */ }

Wie man sieht, reichen die Tests aus, um sicherzustellen, dass jede Zeile Code mindestens einmal von den Tests ausgeführt wird.

Ein genauerer Blick verrät uns jedoch, dass das Tool noch Verbesserungsvorschläge in der Verzweigungsüberdeckung (Branch Coverage) hat. Die Detailansicht gibt Aufschluss darüber, an welchen Stellen es hakt. Darum kümmern wir uns nächste Woche.

Fazit

Die Zeilenüberdeckung/-abdeckung ist das einfachste Überdeckungsmaß. Mit diesem kann festgestellt werden, an welcher Stelle die Tests noch ausgebaut werden müssen, damit jede Zeile der Codebasis von den Tests ausgeführt wird. Leider trifft es keine Aussage darüber, ob die Tests auf irgendeine Weise sinnvoll sind.

Welche Fehler es noch in der Cell-Klasse gibt und wie die Qualität der Tests durch Verzweigungsüberdeckung gesteigert werden kann, wird im nächsten Blog gezeigt. Bis dahin: Happy Testing!

Buchrezension Basiswissen für Softwarearchitekten 3 Auflage

Sat, 27 Jul 2019 00:00:00 +0000

Das Buch soll als Vorbereitung für die Prüfung zum iSAQB Certified Professional for Software Architecture Foundation Level dienen. Dazu soll es auf dem aufbauend auf dem Lehrplan alles notwendige Wissen enthalten, das zum Bestehen der Prüfung notwendig ist.

Aufbau

Die Kapitel sind in sich abgeschlossen und beinhalten zu Anfang immer Lernziele, die direkt aus dem Lehrplan entnommen sind. Zum Ende eines jeden Kapitels befindet sich eine Lernkontrolle, die die Punkte aus dem Lehrplan aufgreifen, die in dem jeweiligen Kapitel vermittelt worden sind. Für die Prüfung relevant sind die Kapitel 2-5: Grundlagen von Softwarearchitekturen, Entwurf von Softwarearchitekturen, Beschreibung und Kommunikation von Softwarearchitekturen und Softwarearchitekturen und Qualität. Abgerundet wird das Buch von einem umfangreichen Anhang, der acht Beispielfragen, ein Abkürzungsverzeichnis, ein Glossar und ein umfangreiches Literaturverzeichnis enthält.

Inhalt

Der Inhalt des Buches ist leider nicht aufeinander aufgebaut. Jedes Kapitel steht für sich. Die Darstellung der einzelnen Lehrinhalte wirkt an vielen Stellen sehr knapp, sodass man unbedingt weiter in der verwiesenen Literatur recherchieren sollte. Studiert man den Lehrplan für die Zertifizierung, dann fällt auf, dass teilweise die Lerninhalte aus der Lernkontrolle nur angerissen wurden, oder gar nicht behandelt wurden.

Bewertung

Ich habe zusätzlich zum Buch eine 4-tägige Schulung besucht. Diese war um einiges umfangreicher, obwohl sie sich ebenfalls direkt am Lehrplan orientiert. Von einem Buch zur Prüfungsvorbereitung hatte ich mir ehrlich gesagt das gleiche gewünscht. Dass man die Beispielfragen aus dem Anhang nicht mithilfe des Buches (oder nur sehr schwer, da im Inhaltsverzeichnis nicht ausgewiesen) beantworten kann, hinterlässt einen fahlen Beigeschmack. Das Buch wirkt an vielen Stellen zu knapp. Die besprochenen Dinge sind aber gut aufbereitet und graphisch anschaulich dargestellt. Zu loben sind die zahlreichen Literaturverweise, die unbedingt zum Selbststudium herangezogen werden sollten.

Fazit

Ich kann dieses Buch bedingt weiterempfehlen. Wenn der Schreibstil etwas flüssiger wäre, dann könnte es als guter Einstieg dienen. Leider habe ich keinen wirklichen Zugang zu diesem Buch gefunden.

My Shell-Config on Windows 10

Mon, 1 Apr 2019 00:00:00 +0000

Windows 10 together with the Windows Subsystem for Linux (WSL) is now a great OS for development.
You can easily switch between the powershell and bash and thus test your code on both systems.

What I love in powershell is the ability to start the windows explorer in the current directory with ii ..
You standard bash does not have this feature out of the box (it doesn't know about windows) but you can configure an alias for that:

alias ii='powershell.exe ii'

This works because out of the box, you can use windows commands within your linux running in WSL!

I also love to be able to view each file in its corresponding standard app by just typing start <filename>.
So start index.html will open the index.html from the current folder in chrome.
Again, an alias will add this feature to your bash:

alias start='cmd.exe /c start'

Cool, isn't it?

How about beeing able to run graphical tool on WSL?
Just add

export DISPLAY=127.0.0.1:0

to your ~/.bashrc and start an XServer on your windows machine (I use VcXsrv) and many linux apps will run on Windows within WSL.

Note: This feature is still unsupported and you will et some error messages on the terminal
You might want to use WLinux from the Microsoft Store to minimize these problems.
WLinux is a Linunx optimized for WSL.
It is even pre-configured to easily connect to your windows docker host wihtout having to deactivate security.

Often it is annoying when the prompt shows you the whole path like mnt/c/Users/yourname/projects/yourproject/etc.
Fix this by replacing the prompt setting in your ~/.bashrc with this line:

if [ "$color_prompt" = yes ]; then
    PS1='\[\e[32m\]\u\[\e[m\]:\[\e[33m\]${PWD#"${PWD%/*/*}/"}\[\e[m\]\$ '
else
    PS1='${debian_chroot:+($debian_chroot)}\u@\h:\w\$ '
fi

It will only display your user name and the last two folders of your current directory.

You can do the same for powershell by adding the following to your profile:

function prompt {
    $dateTime = get-date -Format "dd.MM.yyyy HH:mm:ss"
    $currentDirectory = $(Get-Location)
    $UncRoot = $currentDirectory.Drive.DisplayRoot

    write-host "PS $(Split-Path -Leaf $pwd)>" -NoNewline -ForegroundColor Yellow
    return " "
}

To check where you profile is located, just type $profile at the prompt.
It is very likely that it is currently an empty file.

And while you edit your profile, you might also want to add these lines:

$console = $host.ui.rawui
$console.backgroundcolor = "black"
$console.foregroundcolor = "white"
$colors = $host.privatedata
$colors.verbosebackgroundcolor = "Magenta"
$colors.verboseforegroundcolor = "Green"
$colors.warningbackgroundcolor = "Red"
$colors.warningforegroundcolor = "white"
$colors.ErrorBackgroundColor = "DarkCyan"
$colors.ErrorForegroundColor = "Yellow"

These will fix the standard-colors which make some shell output unreadable.

What are your tricks?

The Results are in!

Fri, 2 Nov 2018 00:00:00 +0000

Hacktoberfest turned October into the most productive month of the last year in regards to docToolchain:

Not only did we reach my goal of 10 pull requests for docToolchain, Hacktoberfest also added new features and new contributors to docToolchain!!

Regarding my personal experience with this years hacktoberfest, it was quite more intense than last years.
I already participated in last years hacktoberfest and so this time, I didn't expect to learn much from it.
That was wrong.

I started out to create 5 PRs, and ended with 26 and with a better understanding of git.

"What was so different to last year?" you may ask...

Well, I noticed that I've got several benefits from Hacktoberfest.
A PR shouldn't be a big thing - you do it several times a week, don't you?
No - at least I don't do it. For most projects I work on, I directly commit on branches and merge them.
I only seldom do PRs, and if I do them, they are trivial.

I did a quick survey on twitter and it turns out that quite a lot of devs in my filter bubble also don't do PRs:

on your main project, how do you contribute code?
— Ralf D. Müller™ (@RalfDMueller) 27. Oktober 2018

Also, it is not the same if you do just one PR or a bunch of PRs to the same repository where you have to re-sync your fork, do feature branches and rebases.

Moreover, what you do often turns into a habit...

In addition, contributing to open source is different than closed or inner source.
One big difference is remote work. Yes. An aspect I wasn't aware of.
With open source, you don't sit together in one room and invite the team to a meeting to discuss a change.
Instead you study the code and architecture of a system and then eventually open an issue followed by a PR.
This is all across time zones and countries.
And when your PR gets accepted, it feels very productive.

The part with "you study the code and architecture of a system" is quite important to me.
For most Github repositories, this is the harder part because the available documentation often only tells you how to use the system represented by the code but not how the code works under the hood.

It showed me how important the various kinds of documentation are and that we should start to not only link to the source of the documentation ("improve this doc") but also to the source code of the feature described in the documentation.
I think this would enable more people to contribute.

What are your thoughts on the barriers to contribute?

PS: As promised, I donated 5€ for each PR to the Movember foundation and I doubled the amount to round it up to 100€.

Thanx for supporting docToolchain and the Movember foundation with your PRs!

HttpBuilder-NG

Fri, 10 Aug 2018 00:00:00 +0000

When you write integration tests for your web application, you certainly need an http client.
But there are many on the market - too many and all with different approaches.

I recently learned to love HttpBuilder-NG.
I already was used to the old HttpBuilder which was often used with groovy, so I was quite eager to give the next generation a try.

The approach it implements is totally different to what I was used to.
I just wanted to get a result back and then crawl over the given structure to find the properties I need. But HttpBuilder-NG comes with its own DSL which is very felxible but also has a learning curve.

To make things easier for me, I came up with a generic template for my test approaches:

{% highlight groovy %}

@Grab('io.github.http-builder-ng:http-builder-ng-core:1.0.3')

import static groovyx.net.http.HttpBuilder.configure

def (statusCode, headers, body)

(statusCode, headers, body) = configure {
    request.uri = "http://example.com"
    request.headers = headers
}.get(List) { 
    response.success { FromServer resp, Object body -> 
        [
            resp.statusCode,
            resp.headers,
            body.toString()
        ]
    }
}

{% endhighlight %}

Wrapped in a function, this lets you execute various get requests with a given uri and a set of headersand will retrieve the http statusCode, response headers and the body.

This template is a good starting point for further kind of requests and refinements where you, for instance, do not need all headers but only the location-header of redirects.

As I already mentioned, there are many http clients available. And that is another strenght of HttpBuilder-NG: it is "just" a builder with the most common http clients under the hood.

When you change the dependency from

{% highlight groovy %}

@Grab('io.github.http-builder-ng:http-builder-ng-okhttp:1.0.3')

{% endhighlight %}

{% highlight groovy %}

@Grab('io.github.http-builder-ng:http-builder-ng-core:1.0.3')

{% endhighlight %}

{% highlight groovy %}

@Grab('io.github.http-builder-ng:http-builder-ng-apache:1.0.3')

{% endhighlight %}

you switch the underlying http client from OkHttp to the java core implementation or Apache HttpComponents

Another solution I would like to share is how to disable the client following redirects.
It seems that many people have the problem that they want to modify how the http client behaves in terms of redirects.
When it comes to testing, I always want to follow the redirects manually.
Bit all clients did it automatically.

I googled a lot and was already at a point where I said "I will use the first http client where I manage to disable to follow redirects".
Many hints you find on the web are for older versions or simply seem not to work.

The code which finally worked for me is the following:

{% highlight groovy %}

...

(statusCode, headers, body) = configure {
    request.uri = "http://example.com"
    request.headers = headers
    client.clientCustomizer { builder ->
        builder.followRedirects = false
        builder.followSslRedirects = false
    }
}.get(List) {

...

{% endhighlight %}

Let's start to _model_ our software architecture!

Mon, 5 Feb 2018 00:00:00 +0000

As architect, you are often reminded that you should model your architecture and not just draw diagrams. But have you ever seen a real architecture model?

I've only seen some aspects modeled, not the whole architecture. I use Sparx Enterprise Architect now for aprox. 15 years, but still don't know how to use it the right way and really model my architecture.

why model and not just draw?

But let's first start with the basic question why we should model and not just draw. The results often look the same. And what do I mean by "model"?

I remember a good example which I have read in a book, but I can't remember which one.
(if you know where I have stolen it, please contact me :-)

Imagine, you have a sports car.

Now imagine you have a small replica of this sports car. This is your model.

It might not be like the real thing, but certain aspects are accurate. In this example, often the look is accurate but the engine won't work.

That reminds me of the quote "All models are wrong, but some are useful" by George Box. So wether your model is an exact replica which you put on the shelve in your living room or it is a toy car with which your kids play - these models are useful and make sense for a certain use case, but an engineer might complain that it is wrong in terms of the engine details.

Now imagine you have a detailed replica and you take some photos:

One of the outside view and one of the view from the driver's seat. These might be great picture if you want to sell your car.
One of the motor and one of the bottom of the car. These might be great pictures for a mechanic.

These pictures are the views onto your model.

You also could have drawn those views, but as you can see, it makes more sense to first create the model and then the views.

It is the same with software architecture. Think about it!

PS: in this example, it would have been even easier to take the pictures from the original sports car. But that does only work if your already have the finished product... https://structurizr.com/ by Simon Brown takes this approach.

Diagramme, aber richtig…

Sun, 28 Jan 2018 00:00:00 +0000

Architekturdokumentation besteht hauptsächlich aus Fließtext, Tabellen und Diagrammen. Fließtext und Tabellen sollten nach der letzten Folge kein Problem mehr sein. Jetzt zeigen wir Ihnen mehrere Optionen, Diagramme in Ihre Dokumentation zu integrieren: Einerseits den einfachen Weg des Referenzierens (mit einigen möglichen Optionen) und alternativ Diagrams-as-Code, was gut zu Titel und Inhalt dieser Kolumne passt. So viel sei allerdings schon verraten: Leider eignet sich der letztgenannte (PlantUML-basierte) Ansatz nur für ganz wenige Arten von Diagrammen. Aber eins nach dem anderen – fangen wir mit den einfachen Dingen an.

weiterlesen auf jaxenter.de

Den mittlerweile sechsten Teil der Kolumne finden Sie in der aktuellen Ausgabe 03.2018 des JavaMagazins

AsciiDoc-Features für Pragmatisches

Sun, 21 Jan 2018 00:00:00 +0000

In den letzten Ausgaben haben wir gezeigt, wie Sie AsciiDoc-Dokumente modular aufbauen und in verschiedene Zielformate wie PDF, DOCX oder Confluence konvertieren können. Diesmal gehen wir auf ein paar der Features von AsciiDoc ein, die unserer Meinung nach bei Architekturdokumentation nützlich sein können.

weiterlesen auf jaxenter.de

Den mittlerweile fünften Teil der Kolumne finden Sie in der aktuellen Ausgabe 02.2018 des JavaMagazins

Open Source is GREAT!

Sun, 14 Jan 2018 00:00:00 +0000

Some thing you just have to experience yourself before you realize it.
One of those things is the power of open source.

I am just now sitting over a new project where I need some documentation.
So I just installed the current version of "my own" open source project docToolchain
and had to realize that I first had to study the manual on how to install the current version.

The project evolved without me and now has the option to be installed as a tool which is invoked through the doctoolchain command instead of beeing a geeky gradle script.

This aspect of Open Source Software is underestimated by many companies who fear that if they open source software, they lose the value of their software to the community.
But for certain types of software, the opposite is the case.
The software is enriched by the community and you get back a value which can be much higher than the original value you had in your software.

The basis for this effect is a great community.

So, again - thanx to all of you who support docToolchain and other open source projects!
The world relies on open source and hence relies on you!

looking back at a great 2017

Sun, 7 Jan 2018 00:00:00 +0000

The year is already seven days old, but it is still time to take a quick look back.

2017 was a great year for me regarding my community activity and the progress of my open source project docToolchain.

This year, I had several chances to talk about Spock & Geb (thanx to DevOpsWuerzburg for inviting me and Tobias Kraft for giving me the chance to be his co-speaker) and Docs-as-Code plus docToolchain (thanx to JAX, the Software Architecture Summit and the JUG Darmstadt for inviting me and to Falk Sippach for combining our talks!). The slides are all available on speakerdeck.

A special thank you goes out to Gernot Starke who helped me to prepare the JAX-Talk and Architecture Summit-Workshop and let me be his co-speaker! Together we also wrote the Hitchhiker’s Guide to Docs as Code as series of articles for the german Java Magazin.

These where all great experience and I hope I can build on these this year. I already have a slot for a talk about docs-as-code at the Entwicklertag Frankfurt and I hope more chances will come up.

The best about all these events where the talks with you - the audience - afterwards and the feedback I could collect. Documentation as a topic seems to be more interesting than I thought and people see that the docs-as-code aproach makes sense.

This is also reflected by the momentum the docToolchain project gained this year. It now has a full blown manual and more than eight contributors who contributed 2017 more features than I did. So it is now a project which is owned by the community - that's a great feeling! Thanx to all of you!

Through the community contributed features, docToolchain gained the ability to export Excel, PPT and Visio. There will soon be a point where I have to split the architecture diagram into several ones:

Speaking of this diagram - docToolchain even managed to be referenced in the newest edition of Gernot Starkes book "Effektive Softwarearchitekturen"!

I nearly forgot to mention that docToolchain was also mentioned by Simon Brown in one tweet together with Grady Booch - isn't that cool?

I did a short interview at @VoxxedAthens with @katharineCodes recently -> https://t.co/l0mWJ2ioy0 … hat tips to @Grady_Booch & @docToolchain
— Simon Brown (@simonbrown) 30. Juni 2017

(btw: I love the C4 approach invented by Simon Brown and his books on Software Architecture for Developers)
I am also very happy that the year gave me lots of chances to meet many of those great people from my twitter time line and talk over a pizza or a beer with them. I learned a lot from all of you!

We are dwarfs standing on the shoulders of giants - in this sense, I would also like to thanx the Asciidoctor, the Apache Groovy and Gradle project teams who all created the wonderful basis for docToolchain.

Hope to see you all again in 2018!

Dokumentationen als Code

Fri, 29 Dec 2017 00:00:00 +0000

In der letzten Folge dieser Kolumne haben wir gezeigt, wie Sie Ihre AsciiDoc-Dokumente modular aufbauen können.
In der dritten Folge der Kolumne erklären wir am Beispiel der Formate PDF, DOCX, Confluence und EPUB, wie sich verschiedene Ausgabeformate aus Ihrem AsciiDoc-Input erzeugen lassen.

weiterlesen auf jaxenter.de

Den mittlerweile fünften Teil der Kolumne finden Sie in der aktuellen Ausgabe 02.2018 des JavaMagazins

Modulare Dokumentationen

Wed, 8 Nov 2017 00:00:00 +0000

In der letzten Ausgabe haben wir gezeigt, wie Sie mithilfe von AsciiDoc schnell zu ordentlich gestalteten Dokumenten kommen können.
In der zweiten Folge unserer Kolumne möchten wir Ihnen Strukturierung und Modularisierung von Dokumentation vorstellen, einerseits zur Erleichterung von Teamarbeit, andererseits zur Verwendung einzelner Dokuteile für verschiedene Zielgruppen.

weiterlesen auf jaxenter.de

Den dritten Teil der Kolumne finden sie in der aktuellen Ausgabe 12.2017 des JavaMagazins

Neue Kolumne

Wed, 18 Oct 2017 00:00:00 +0000

Dokumentation gehört zu den großen Übeln der Softwarezunft.
Denn Software zu dokumentieren ist oft mühselig, zeitraubend und schlicht und ergreifend langweilig.
Dass dem nicht so seien muss, zeigen die beiden Autoren Gernot Starke und Ralf D. Müller in ihrer neuen Kolumne.
Ihr Ansatz ist die Dokumentation wie Code zu behandeln: Docs as Code.

weiterlesen auf jaxenter.de

plantUML with Asciidoctor-pdf

Mon, 1 May 2017 00:00:00 +0000

The last few days I had to learn the hard way that plantUML (as part of asciidoctor-diagram) is not a frient of asciidoctor-pdf.

I always thought that having plantUML for HTML rendering up and running with asciidoctor also means that the PDF backend would be running fine.

Unfortunately, asciidoctor-pdf is looking in the source-folder for the generated plantUML images and can't find them there.

I didn't quite get the whole picture - which module is picking up the images from where or generates them in which folder, but I got the impression that the problem is quite complex.
Dan Allen pointed me to some comments which describe solutions (the Asciidoctor community is really great), but while I was trying to find a solution which fits my case, I got the feeling that I will get standard images or plantUML up and running, but not both.

I've now got a solution which I think is quite ok:

First, I splitted the generation of HTML and PDF into two seperate tasks:

{% highlight gradle %}
tasks.withType(AsciidoctorTask) { docTask ->
outputDir = file(targetDir)
sourceDir = file(srcDir)

    'pdf-stylesdir': 'pdfTheme',
        'pdf-style': 'custom',
        'source-highlighter': 'coderay',
        'imagesdir': 'images',
        'toc': 'left',
        'icons': 'font',
        'javaVersion'         : "$javaVersion",
        'currentDate'         : "$currentDate",
        'allow-uri-read'      : true
// ...

// configure source and output files and folders
sourceDir = file('src/docs')
sources {
    include 'arc42-venom.adoc'
    include 'index-orga.adoc'
}
outputDir = file('build/docs')
// good to see what the build is doing...
logDocuments = true

requires = ['asciidoctor-diagram']

}

task generateHTML (
type: AsciidoctorTask,
description: 'use html5 as asciidoc backend') {
attributes
'plantUMLDir' : ''
backends = ['html5']
}

task generatePDF (
type: AsciidoctorTask,
description: 'use html5 as asciidoc backend') {
attributes
'plantUMLDir' : file('build/docs/images/plantUML/').path
backends = ['pdf']
}
{% endhighlight %}

Second (already included in the source above), I added an attribute plantUMLDir which specifies the absolute path to a folder where I want to have my plantUML images generated to.

So, my trick now is to use this absolute path in my plantUML diagram definitions

[plantuml,"{plantUMLDir}image_name",png]

and this seems to work :-)

for HTML, plantUML images are referenced relative to the document
for PDF, plantUML images are are referenced absolute, but since they are stored within the pdf, this does not matter
images are rendered ok in HTML and PDF
plantUML is rendered ok in HTML and PDF
plantUML files are created in build-folder

systematically improve code and structures

Mon, 10 Oct 2016 00:00:00 +0000

Last week, I had the chance to attend a three day training on how to systematically improve software systems. It is called "IMPROVE" and is given by Dr. Peter Hruschka and Dr. Gernot Starke. The german description can be found here: http://www.arc42.de/improve.html

The training is based on the aim42 initiative and enriched by the broad knowledge and experience of the two speakers. What I liked most where the two parts on how to do estimates the right way and how to convince the management to let you work on technical debt.

Today I already started to implement what I learned and created a technical debt list for docToolchain and tomorrow I will start to put estimates on each issue...

More can be found on the english website of aim42.

Reduzierte Wartungskosten durch evolutionäre Verbesserung: https://t.co/soZUqvXXPx Trainingsimpressionen mit Peter Hruschka & @gernotstarke pic.twitter.com/6066CrxLIY
— arc42 (@arc42Tipps) 7. Oktober 2016

Bauen versus Basteln - @gernotstarke über die teilweise grotesken Zustände der SW-Entwicklung https://t.co/FAVymyzcc6 #aim42 #architecture
— arc42 (@arc42Tipps) 7. Oktober 2016

Groovy is Java is Groovy...

Mon, 9 May 2016 00:00:00 +0000

There still seem to be some Java-Developers who are afraid of
mixing their Java codebase with the power of Groovy.

Some time ago, it was a valid argument that the dependency
to the groovy-all.jar would blow up the generated application,
but today many frameworks like Jasper-Reports, Apache-Camel and others might already add the
groovy-all.jar to the class path of your application. So there is no reason anymore
not to use Groovy in your project.

The following snippets will show you how easy it is to combine Java und Groovy, because Groovy is Java and Java is Groovy...

This example assumes that you have Groovy and Java installed and groovy-all-2.4.6.jar is available in your work directory.

Create a simple Java class which just greets Groovy:

HelloGroovy.java

public class HelloGroovy {
	public static void main(String[] args) {
		System.out.println("Hello Groovy. This is java!");
	}
}

...and compile it...

javac -cp . HelloGroovy.java

Now create a Groovy-Script which greets Java and calls the Java class from above

HelloJava.groovy

println "Hello Java, this is Groovy!"
HelloGroovy.main(); //call the first java-snippet

...and compile it...

groovyc -cp . HelloJava.groovy

Now create a third file which contains a Java class which calls the class created by the Groovy-Script

Test.java

class Test {
	public static void main(String[] args) {
		System.out.println("Java & Groovy = Dream-Team!");
		HelloJava.main();
	}
}

...and compile it. This time, we need the groovy-all.jar in the classpath:

javac -cp ".;groovy-all-2.4.6.jar" Test.java

That's it. Now let's execute the test class:

$ java -cp ".;groovy-all-2.4.6.jar" Test
Java & Groovy = Dream-Team!
Hello Java, this is Groovy!
Hello Groovy. This is java!

Wasn't that easy?

PS: yes, this is very old knowledge, but sometimes the good things have to be repeated over and over again...

A Groovy Notebook

Sat, 30 Apr 2016 00:00:00 +0000

From time to time I stumble upon a web application which lets you write notebooks like the ones you know from Mathematica. They let you mix formatted text which explains your code with code snippets. The output of those snippets is displayed and the code builds up snippet by snippet.

Taken from the Jypter Blog

This time it was Jypiter, formerly known as IPython Notebook. It evolved from a notebook just for Python to a cool solution suitable for all kind of languages. Unfortunately, Groovy isn't yet in the list of supported languages.

Since Python is not my mother tongue and I couldn't find good documentation on how to support an additional language, I thought about other ways to create a notebook for Groovy.

Inspired by the talk "Make your Asciidoctor Groovy" by Stephan Classen (which I unfortunately haven't attended), I decided to create an asciidoctorj plugin in Groovy which lets you execute Groovy code inline.

There are already great examples of plugins written in Groovy, so I had a good starting point:

Stephan Classen: asciidoctorj-screenshot
mrhaki: Awesome Asciidoctor: Write Extensions Using Groovy (or Java)
Andreas Almiray: Gradle Glam: custom asciidoctor extensions

So I took one of them as starting point and came up with my own project. The core of the extension is shown here:

It is activated whenever asciidoctor hits a [groovy] block. It then takes the content of the block, executes it and renders the original script together with the output. Infortunately, I couldn't find a way to return two different blocks in my extension - one which renders the source with highlighting and one which renders the pre-formatted output - so I had to do an ugly workaround which directly renders HTML. Do the simplest think which works :-)

Here is an example of the static rendered output: example.html with the corrsponding input.

Wacom Bamboo Spark - could have been so much more...

Thu, 28 Apr 2016 00:00:00 +0000

Bad news first: I guess I do not belong to the target group of the Wacom Bamboo Spark :-)

My week began with a Mail from Amazon telling me that there they have a special offer for one of my Wishlist items: the Bamboo Spark digital notepad. I couldn't resist and ordered it, but sone came doubts: do I have any use case for it?

Yesterday the Spark arrived. As always with Wacom, the unboxing gives you the feeling that you've made the right decision and have bought a well designed product. The setup is also a no brainer and you can start to write and sketch immediately. The pen feels like a normal pen and the paper - well it is just normal paper.

The digitizer works very accurate. The simple status LED shows you if you are on a blank page (from the Spark's point of view) or if it already has some content. A press of the button advanced to the next blank page.

The sync with the mobile device seems to be activated whenever you switch to a new blank page. There is no other control to start the sync. That's something I had to figure out, but it is ok. As soon as the pages are synced to the wacom cloud, you can convert them to plain text, PDF or image. The text recognition works quite well, even for mixed language content.

So far so good. If you want to sync what you've written and sketched, this product is perfect. But that seems to be all functionality you get with the bamboo spark app. Nothing more. So, I guess there are people who need exactly this functionality and for them, the bamboo spark is the perfect product.

But I hoped to get a bit more

compared to scanner apps like Whitelines Link it could be much more intelligent. Whitelines only captures the paper by camera, but it offers three checkboxes through which you can tell the app to directly store the captures image in evernote, dropbox or send it via mail. Such a functionality should be a quick win for wacom
the spark uses "the soon-to-be industry standard WILL™ universal ink files". But when you try to get more information about this format, you have to sign agreements in order to get the SDK. WILL seems to be a zip file with a binary data file as main content. It would have been nice if the file format would have been easier to use.
but you can also export your written notes as plain text. And this seems to be the key to additional, self build functionality

Ideas on how to hack the functionality

Plain Text Processing

Since the first anoto smart pens like the livescribe smartpen hit the market, I dreamed of functionality where you use plain paper to create input for our personal digital assistant (PDA) as the devices where called back then. Today I would like to use the bamboo spark to interact with my smartphone. Here are basically three simple use cases

1. write a simple note and send it via mail

This could be as simple as writing a note like this on the spark:

mailto: someone@example.com
Please don't forget to send me that info...
Cheers,
Ralf

2. write a to-do which will added to your favorite to-do list

same pattern:

ToDo: buy some beer for the party next weekend

3. ... or add something to your calendar

Date: 29.04. 19:00 Java User Group Meetup

And yep, it basically works! You can scribble these notes on the spark, convert them to text and then send them - for instance as email - to a script which does a further processing. Not build in, but possible and easy to implement. But this is unfortunately not an automated step since there is no API for the wacom cloud (at least none I am aware of) and so you have to convert your notes manually to plain text and send them. Each page by its own :-(

Extract Graphical Data

Another Idea is to process the strokes for additional functionality. The system should be able to give you the timing of the strokes along with the strokes themselves. So in addition to the OCR, you could implement functionality like the whitelines checkboxes - the system should be able to recognize a checkmark in a certain position or a special symbol.

The WILL format seems to be the right way, but since it is proprietary, I don't want to take this route. It would be different if it would be more open.

So I checked the exported PDF - bingo. The PDF contains not the strokes but the drawing - e.g. for each line a polygon which describes the border of the stroke. And those polygons seem to be even in the order of drawing. In order to give it a try, I create a small javascript which visualizes the PDF drawing:

tl;dr

The wacom bamboo spark is a great tool if you want to have digital copies of your handwritten sketches and notes. But unfortunately there is no extra functionality out of the box. Hacking is possible, wacom could make it easier.

Serialize a Map as JSON or YAML

Wed, 6 Apr 2016 00:00:00 +0000

When working in a web environment, you often have to transfer arbitrary data like lists or maps as String of the network.

The followin Gist shows how to solve this by serializing a list or map as JSON or YAML. In addition, it
shows how Groovy does it an a very elegant and clean way.

Jatumba!

Thu, 10 Mar 2016 00:00:00 +0000

Zwei Tage Javaland liegen gerade hinter mir. Zusammen mit Tobias Kraft hatte ich die tolle Gelegenheit unseren Vortrag über Spock und Geb nochmal vor einem größeren Publikum vorzutragen.

Die zwei Tage waren natürlich vollgepackt mit Vorträgen, gutem Essen und guter Laune. Im Netzt gibt es schon einige gute Zusammenfassungen der Tage z.B. bei exensio und develishdevelop.

Für mich waren folgende Vorträge am interessantesten:

Dierk König "Fun in GroovyLand": Wie Tobias schon geschrieben hat, super Vortragsstil trotz ausgefallener Technik. Und @canonical + @builder haben sich bei mir als nützliche Annotation eingeprägt
Daniel Grycman "Introduction to Agile Documentation": selbst noch nicht gesehen, soll aber gut gewesen sein, da AsciiDoc ;-)
MrHaki "Writing Documentation with Asciidoctor Is Awesome": Toller Vortragsstil mit Live-Coding über ein langes Asciidoc-Dokument
Andreas Knuth "PhantomJS - Schweizer Taschenmesser der WWW-Automatisierung": Interessante Einblicke über die unter PhantomJS liegende Technologie und warum wir PhantomJS-CEF brauchen.
Alexander Heusingfeld und Tammo van Lessen "When Microservices Meet Real-World Projects: Lessons Learned": Super Tipps und eine Leand-Deployment-Pipeline (Pull statt Push!) -> Slides
Markus Schlichting "Token statt Cookies dank JWT": genau, was ich gesucht habe, um meine JSESSIONID los zu werden! -> Slides

Lots of people interested in Testing with Spock and Geb with @tokraft and @RalfDMueller at #JavaLand pic.twitter.com/f7XBxrNHCl
— Florian Hopf (@fhopf) 8. März 2016

Testing automated with #Selenium #WebDriver, #Geb and #Spock demonstrated by @tokraft at #JavaLandConf 👌 pic.twitter.com/ssQBhCjtNj
— Markus ★ (@madmas) 8. März 2016

Wer den Vortrag verpasst hat, kann sich das Video vom Entwicklertag letzten Jahres nochmal ansehen:

Domain Class Diagrams for Grails Projects

Fri, 14 Aug 2015 00:00:00 +0000

A Grails project can quickly grow into larger applications. In order to still keep an overview, some architecture documentation is quite useful. One of the most useful diagrams to dive into an application is the domain class diagrams which shows you how your business or domain object interact.

There are a lot of tools on the market which let you analyze and reverse engineer your project in order to draw such a class diagram. They fall in two categories:

Tools which automatically create and layout your diagram
Tools which let you manually enhance the diagram after discovering your classes

For the first category, there are some Grails plugins which use tools like PlantUML to draw the needed diagrams right from within the Grails framework. That's great to get a quick overview, but since you can't easily enhance the diagrams with additional information or lay out the elements with your wisdom, I don't like them to create my project documentation.

There are great tools within the second categroy, but unfortunately, I am not aware of a single one which is capable of doing the trick for Groovy classes - only Java ones. Some of them are highly configurable and it would be possible to teach them how to work with Groovy. But the effort to do so is high. For Enterprise Architect by Sparx Systems, you need Groovy descirbe as EBNF - I am currently not aware of an EBNF description and it would be hard to create and maintain one by myself.

So what to do? Groovy already looks like Java and Grails knows about its domain classes. So my approach is to use a script which takes the knowledge about the domain classes available within grails and creates Java classes from it.

These classes then can be easily fed into whatever UML tool you chose. As Result, you will have

an easy way to export and synchronize your Grails domain classes to any UML tool capable of analyzing Java sources
depending on you Tool, you are free to manually add your knowledge and lay out the diagrams as you like
most tools keep your manual layout and additions even when you re-synchronize the diagrams with your code

Details of the Solution

As already mentioned, I use the information already available in Grails. In order to do so, I wrote a Grails script which is invoked from the command line. The following Gist shows you the code.

Unfortunately, Grails only knows about the code, not the comments which are available within the source. So I added a little dirty hack which fetches the source of the domain class and extracts the first comment - hopefully the description of the domain class - and adds it to the java sources.

In order to make it even more convenient, you can check out your UML-Tool and see if it let's you automate the synchronisation with your generated code.

Example

Here is an example diagram for the Grails PetClinic sample application created with Enterprise Architect.

Spock-Reports for Grails 2.5

Thu, 16 Jul 2015 00:00:00 +0000

In two previous posts (Grails3.0 & Grails2.2) I described how to use Spock-Reports with Grails 3.0 and Grails 2.2.

Now, if you try to use it with Grails 2.5, it seems not to work from the start. The main problem I noticed was that even
when I run a trivial app and all spock tests are auto-created, I got an error message at the end of the tests:
http://stackoverflow.com/questions/31440381/forked-grails-vm-exited-with-error-while-running-test-app#comment50863764_31440381

So I tried to get rid of this error message by not forking the VM when running tests. To do that, simply set the fork-configuration
to false for the test environments (in BuildConfig.groovy)

grails.project.fork = [
    ...
    test: false,
    ...
]

Now, the rest seems to work the same as with Grails 2.2.4 with the only difference that Grails 2.5 uses Spock out of the box.
So we don't habe to configure it:

just open your grails-app/conf/BuildConfig.groovy file and add

repositories {
  [...]
  //for spock-reports
  mavenRepo "http://jcenter.bintray.com"
}

to the repositories section and

dependencies {
  [...]
  //for spock-reports
  test 'com.athaydes:spock-reports:1.2.5'  
}

to the dependencies section.

The standard reports are now generated and stored in build/spock-reports/..

Customizing your Reports

In order to store the generated reports in target/test-reports/spock/. you have to customize your reports as described in the documentation, you have to create a file called META-INF/services/com.athaydes.spockframework.report.IReportCreator.properties.
That sounds easier than it is, because it has to be in the classpath and for some Grails projects, it's not easy to find the right folder to put it.

For Grails 2.5, you will succeed by putting it in grails-app/conf/META-INF/services/com.athaydes.spockframework.report.IReportCreator.properties.

Here is a sample file which uses the template based reports:

# Name of the implementation class of the report creator
# Currently supported classes are:
#   1. com.athaydes.spockframework.report.internal.HtmlReportCreator
#   2. com.athaydes.spockframework.report.template.TemplateReportCreator
com.athaydes.spockframework.report.IReportCreator=com.athaydes.spockframework.report.template.TemplateReportCreator

# Output directory (where the spock reports will be created) - relative to working directory
com.athaydes.spockframework.report.outputDir=target/test-reports/spock

# If set to true, hides blocks which do not have any description
com.athaydes.spockframework.report.hideEmptyBlocks=false

# Set properties of the report creator
com.athaydes.spockframework.report.template.TemplateReportCreator.specTemplateFile=/spockreporttemplate/spec-template.md
com.athaydes.spockframework.report.template.TemplateReportCreator.reportFileExtension=md
com.athaydes.spockframework.report.template.TemplateReportCreator.summaryTemplateFile=/spockreporttemplate/summary-template.md
com.athaydes.spockframework.report.template.TemplateReportCreator.summaryFileName=summary.md

this file specifies that the templates are located in grails-app/conf/spockreporttemplates and the output
will be written to target/test-reports/spock. A good idea is to start with the default templates spec-template.md and summary-template.md

You might want to use this https://github.com/rdmueller/Grails2.5-Spock-Reports-Sample as a starting point...

Spock-Reports for Grails 2.2

Tue, 14 Jul 2015 00:00:00 +0000

In a previous post I described how to use Spock-Reports with Grails 3.0.

That was easy since Grails 3.0 is Gradle based.

Now I will try to figure out how to use Spock-Reports with Grails 2.2.4 .

Again, the configuration of the dependencies is easy: just open your grails-app/conf/BuildConfig.groovy file and add

repositories {
  [...]
  //for spock-reports
  mavenRepo "http://jcenter.bintray.com"
}

to the repositories section and

dependencies {
  [...]
  //for spock-reports
  test 'com.athaydes:spock-reports:1.2.5'  
}

to the dependencies section. But since Grails 2.2.4 does not include Spock be default, we also have to follow the
documentation for the Grails-Spock-Plugin and add in addition

plugins {
  [...]
	test(":spock:0.7") {
	    //since we use groovy 2.x with grails 2.2.4
      	    exclude "spock-grails-support"
    	}
}

to the plugins section and

dependencies {
  [...]
  test 'org.spockframework:spock-grails-support:0.7-groovy-2.0'
}

to the dependencies section. Now, that should do the trick. The standard reports are now generated and stored in build/spock-reports/..

Customizing your Reports

For Grails 2.2.4, you will succeed by putting it in grails-app/conf/META-INF/services/com.athaydes.spockframework.report.IReportCreator.properties.

Here is a sample file which uses the template based reports:

# Name of the implementation class of the report creator
# Currently supported classes are:
#   1. com.athaydes.spockframework.report.internal.HtmlReportCreator
#   2. com.athaydes.spockframework.report.template.TemplateReportCreator
com.athaydes.spockframework.report.IReportCreator=com.athaydes.spockframework.report.template.TemplateReportCreator

# Output directory (where the spock reports will be created) - relative to working directory
com.athaydes.spockframework.report.outputDir=target/test-reports/spock

# If set to true, hides blocks which do not have any description
com.athaydes.spockframework.report.hideEmptyBlocks=false

# Set properties of the report creator
com.athaydes.spockframework.report.template.TemplateReportCreator.specTemplateFile=/spockreporttemplate/spec-template.md
com.athaydes.spockframework.report.template.TemplateReportCreator.reportFileExtension=md
com.athaydes.spockframework.report.template.TemplateReportCreator.summaryTemplateFile=/spockreporttemplate/summary-template.md
com.athaydes.spockframework.report.template.TemplateReportCreator.summaryFileName=summary.md

You might want to use this https://github.com/rdmueller/Grails2.2-Spock-Reports-Sample as a starting point...

A Fool with a Tool is still a Fool...

Sun, 12 Jul 2015 00:00:00 +0000

...but sometimes the tool makes a difference!

I just came back from an interesting 3 day workshop on which I had a first
chance to make use of my drawing equipment I bought recently. Originally, I wanted to draw some slides for my talk at
Entwicklertag Karlsruhe but we later dropped the idea in favour of professional clip art.

But since we've had a flip chart available at the workshop and I thought that creating power point slides would take too much
time when only 3 days are available, I gave it a try:

Diese Abbildung wurde inspiriert durch die bikablo® Publikationen, www.kommunikationslotsen.de

I used my [neuland "fine One" set of artmarkers](http://de.neuland.com/marker-und-stifte/neuland-marker/fineone-by-neuland-artmarker-pinselpitze-13er-farbset.html?c=725) and my [bikablo-books](http://bikablo.kommunikationslotsen.de/bikablo-produkte/) with lot's of ideas on how to visualize ideas and then started to draw. The feedback I've got was great!

The "fine One" markers are not the best for a flip chart - they are designed for smaller format, but the do work on larger formats too.
The brush tip gives your drawings a professional look which is visibly different from standard flip chart markers. The different light colors enable you to colorize your visualisations and give them the finishing touch.

Btw: after I had my first results with the artmarkers, I bought myself a Wacom Intuos drawing tablet (CTH-480) and searched for good and affordable drawing software to recrate the effects I created with the artmakers. I found InkScape to be the most convenient and free tool. This is the result:

Diese Abbildung wurde inspiriert durch die bikablo® Publikationen, www.kommunikationslotsen.de

If you have any hints on how to get better results (I guess there is better software :-) please tell me!

Spock-Reports for Grails 3.0

Sat, 11 Jul 2015 00:00:00 +0000

Spock-Reports is a great way to create better reports for Spock.

Since Grails 3.0 is based on Gradle, integrating the Spock-Reports is easy. Just open your build.gradle file and add

repositories {
  [...]
  //for spock-reports
  jcenter()
}

to the repositories section and

dependencies {
  [...]
  //for spock-reports
  testCompile 'com.athaydes:spock-reports:1.2.5'  
}

to the dependencies section.

that's it... The next time you run grails test-app, you'll find the generated Spock-Reports in /build/spock-reports/

Customizing your Reports

If you want to customize your reports as described in the documentation, you have to create a file called META-INF/services/com.athaydes.spockframework.report.IReportCreator.properties. That sounds easier than it is, because it has to be in the classpath and for some Grails projects, it's not easy to find the right folder to put it.

For Grails 3.0, you will succeed by putting it in src/test/resources/META-INF/services/com.athaydes.spockframework.report.IReportCreator.properties.

Here is a sample file which uses the template based reports:

# Name of the implementation class of the report creator
# Currently supported classes are:
#   1. com.athaydes.spockframework.report.internal.HtmlReportCreator
#   2. com.athaydes.spockframework.report.template.TemplateReportCreator
com.athaydes.spockframework.report.IReportCreator=com.athaydes.spockframework.report.template.TemplateReportCreator

# Output directory (where the spock reports will be created) - relative to working directory
com.athaydes.spockframework.report.outputDir=build/spock-reports-mds

# If set to true, hides blocks which do not have any description
com.athaydes.spockframework.report.hideEmptyBlocks=false

# Set properties of the report creator
com.athaydes.spockframework.report.template.TemplateReportCreator.specTemplateFile=/spockreporttemplate/spec-template.md
com.athaydes.spockframework.report.template.TemplateReportCreator.reportFileExtension=md
com.athaydes.spockframework.report.template.TemplateReportCreator.summaryTemplateFile=/spockreporttemplate/summary-template.md
com.athaydes.spockframework.report.template.TemplateReportCreator.summaryFileName=summary.md

this file specifies that the templates are located in src/test/resources/spockreporttemplates. A good idea is to start with the default templates spec-template.md and summary-template.md

You might want to use this https://github.com/rdmueller/Grails3.0-Spock-Reports-Sample as a starting point...

Spock und Geb - Übersichtlich und nachvollziehbar Testen für alle!

Sun, 5 Jul 2015 00:00:00 +0000

Auf dem Entwicklertag Karlsruhe hatte ich zusammen mit Tobias Kraft mal wieder die Möglichkeit meine Ideen in einem Vortrag
zu präsentieren. Mittlerweile ist sogar das Video zum Vortrag online.

In dem Vortrag geht es darum, wie man bei der Entwicklung einer webbasierten Anwendung zusammen mit dem Kunden (Product Owner) eine "Testfahrt" der Applikation planen, automatisch ausführen und einen aussagekräftigen Report erstellen kann.

Viel Spass beim ansehen!

Spock-Reports with Templates

Sun, 15 Mar 2015 00:00:00 +0000

The new template engine for the Spock-Reports-Plugin is out. Let's build an asciidoc template with it.

Step 1: configure the plugin

Renato describes this step in detail on the Plugin Homepage. I've placed the properties file in src/test/resources/main/META-INF/services/ and so I place my templates also in src/test/resources/spockreporttemplate/

com.athaydes.spockframework.report.template.TemplateReportCreator.specTemplateFile=/spockreporttemplate/spec-template.ad
com.athaydes.spockframework.report.template.TemplateReportCreator.reportFileExtension=ad
com.athaydes.spockframework.report.template.TemplateReportCreator.summaryTemplateFile=/spockreporttemplate/summary-template.ad
com.athaydes.spockframework.report.template.TemplateReportCreator.summaryFileName=summary.ad

Just to get started, I placed two emtpy files spec-template.ad and summary-template.ad at the right location and ran my tests just to see that those empty templates are picked up.

Step 2: create a summary template

I'll start with the summary report. It seems to be the easier one. Renato already provided a markdown sample, so let's take a look at it to see the data which is available to the template.

So it seems that we have a convinience function (aggregateStats) which creates some statistical data about our test runs and the data object itself.

Let's modify the empty template in order to output both data structures:

<% def stats = com.athaydes.spockframework.report.util.Utils.aggregateStats( data ) %>
${stats.inspect()}
>>>>>>>>>>
${data.inspect()}

which leads to the following output: (a little bit reformatted for better readability)

['total':13, 'passed':13, 'failed':0, 'fFails':0, 'fErrors':0, 'time':258.0, 'successRate':1.0]
>>>>>>>>>>
['DatabaseDrivenSpec':['failures':0, 'errors':0, 'skipped':0, 'totalRuns':1, 'successRate':1.0, 'time':67], 
	'DataDrivenSpec':['failures':0, 'errors':0, 'skipped':0, 'totalRuns':3, 'successRate':1.0, 'time':19], 
	'DerivedSpec':['failures':0, 'errors':0, 'skipped':0, 'totalRuns':2, 'successRate':1.0, 'time':16], 
	'EmptyStackSpec':['failures':0, 'errors':0, 'skipped':0, 'totalRuns':4, 'successRate':1.0, 'time':20], 
	'HamcrestMatchersSpec':['failures':0, 'errors':0, 'skipped':0, 'totalRuns':1, 'successRate':1.0, 'time':21], 
	'HelloSpockSpec':['failures':0, 'errors':0, 'skipped':0, 'totalRuns':1, 'successRate':1.0, 'time':3], 
	'IncludeExcludeExtensionSpec':['failures':0, 'errors':0, 'skipped':0, 'totalRuns':3, 'successRate':1.0, 'time':3], 
	'OrderedInteractionsSpec':['failures':0, 'errors':0, 'skipped':0, 'totalRuns':1, 'successRate':1.0, 'time':49], 
	'PublisherSpec':['failures':0, 'errors':0, 'skipped':0, 'totalRuns':2, 'successRate':1.0, 'time':24], 
	'StackWithOneElementSpec':['failures':0, 'errors':0, 'skipped':0, 'totalRuns':4, 'successRate':1.0, 'time':4], 
	'StackWithThreeElementsSpec':['failures':0, 'errors':0, 'skipped':0, 'totalRuns':4, 'successRate':1.0, 'time':7], 
	'StepwiseExtensionSpec':['failures':0, 'errors':0, 'skipped':0, 'totalRuns':3, 'successRate':1.0, 'time':4], 
	'UsingJUnitRulesSpec':['failures':0, 'errors':0, 'skipped':0, 'totalRuns':1, 'successRate':1.0, 'time':21]
]

That's great! We get hashmaps which can be easily inspected. That will make it even easier to write a template.

Now let's come up with the real template:

summary-template.ad:

<% def stats = com.athaydes.spockframework.report.util.Utils.aggregateStats( data )
 %>= Specification run results

== Specifications summary

[small>#created on ${new Date()} by ${System.properties['user.name']}#

.summary
[options="header"]
|==================================================================================================================================
| Total          | Passed          | Failed          | Feature failures | Feature errors   | Success rate        | Total time (ms) 
| ${stats.total} | ${stats.passed} | ${stats.failed} | ${stats.fFails}  | ${stats.fErrors} | ${stats.successRate}| ${stats.time}   
|==================================================================================================================================

== Specifications

[options="header"]
|===================================================================
|Name  | Features | Failed | Errors | Skipped | Success rate | Time 
<% data.each { name, map ->
 %>| $name | ${map.totalRuns} | ${map.failures} | ${map.errors} | ${map.skipped} | ${map.successRate} | ${map.time} 
<% } %>
|===================================================================

[small]#generated by ${com.athaydes.spockframework.report.SpockReportExtension.PROJECT_URL}[Athaydes Spock Reports]#

Since MarkDown and AsciiDoc do not differ too much for this template, this was easy! Details regarding the formatting can be solved later...

To check the correct asciidoc syntax, you can simply copy and paste the result to the asciidoc live editor https://asciidoclive.com/

Step 3: create a spec template

Now let's do the same with the spec template. First try to figure out what data we will have available.

${data.dump()}

but this time, the dump does not give us such a good result: (reformatted for readability)

<com.athaydes.spockframework.report.internal.SpecData@5de17399 
info=org.spockframework.runtime.model.SpecInfo@7c6c71f5
featureRuns=[
	com.athaydes.spockframework.report.internal.FeatureRun@33adcba4,
	com.athaydes.spockframework.report.internal.FeatureRun@5714967d,
	com.athaydes.spockframework.report.internal.FeatureRun@8a41535
	] 
totalTime=10>

We can only see the different java object within the dump and not the full data structure. Since I don't like to go to the source of those structure and analyze it, I now take the MarkDown sample template and start to transform it right away. This should lead to a solution which will fit for the moment:

spec-template.ad:

<%  def fmt = new com.athaydes.spockframework.report.internal.StringFormatHelper()
    def stats = com.athaydes.spockframework.report.util.Utils.stats( data )
 %>== Report for ${data.info.description.className}

=== Summary

[cols="asciidoc,asciidoc"]
|====
|* Total Runs: ${stats.totalRuns}
 * Success Rate: ${fmt.toPercentage(stats.successRate)}
 * Total time: ${fmt.toTimeDuration(stats.time)}
|* Failures: ${stats.failures}
 * Errors:   ${stats.errors}
 * Skipped:  ${stats.skipped}
|====

=== Features
<%
    features.forEach { name, result, blocks, iterations, params ->
%>
==== $name

Result: **$result**
<%
        for ( block in blocks ) {
 %>
* ${block.kind} ${block.text}
<%
        }
        def executedIterations = iterations.findAll { it.dataValues || it.errors }
        if ( params && executedIterations ) {
 %>
[options="header"]
|====
| ${params.join( ' | ' )} |
<%
            for ( iteration in executedIterations ) {
%>| ${iteration.dataValues.join( ' | ' )} | ${iteration.errors ? '(FAIL)' : '(PASS)'}
<%          } 
%>|====
<%      }
        def problems = executedIterations.findAll { it.errors }
        if ( problems ) {
            out << "\nThe following problems occurred:\n\n"
            for ( badIteration in problems ) {
                if ( badIteration.dataValues ) {
                    out << '* ' << badIteration.dataValues << '\n'
                }
                for ( error in badIteration.errors ) {
                    out << '----\n' << error << '\n----\n'
                }
            }
        }
    }
 %>

[small]#generated by ${com.athaydes.spockframework.report.SpockReportExtension.PROJECT_URL}[Athaydes Spock Reports]#

The result looks good :-) Now that we have the summary report and all spec reports, we can add a small section to the summary template which includes all spec reports or order to create one big report file:

<% data.each { name, map ->
 %>
<<<<

include::${name}.ad[]
<% } %>

Now we only need to create a gradle task which renders it.

How to use the Spock-Reports-Plugin with Gradle

Sat, 14 Mar 2015 00:00:00 +0000

Since I experienced some problems when I tried to use the Spock-Reports-Plugin in Grails, I now tried to use it with Gradle.

The basics are easy and well described on the Spock-Reports page - just add the needed repository and dependency to your gradle build file:

    ...
    repositories {
        ...
        jcenter()
    }
    ...

    dependencies {
        ...
        testCompile 'com.athaydes:spock-reports:1.2.5'
    }
    ...

But where to place the properties file in case you want to modify some of them (for instance switch to the new template report engine)? Renato just writes that you should copy the properties "to a file at META-INF/services/com.athaydes.spockframework.report.IReportCreator.properties relative to the classpath". Since I am a Gradle newbie, I had to do some experiments before I found out that one place where you can put it is the same as for maven: src/test/resources/. And src/main/resources/ will also work.

Starting a new Blog

Tue, 3 Mar 2015 00:00:00 +0000

Just started my new blog. I've already had several blogs with more or less success, so why do I now start another? First of all because I don't what to be a ghost developer.