Posts on Software Development and IT Operations

Diagrams in documentation, featuring diagrams.net. Virtual Meetup #6 of Continuous Documentation Regulars.

Diagrams in Documentation

When authoring technical documents, we often struggle to find the easiest way to include diagrams. This article lists several diagramming tools and several ways you can use them to enhance the documentation for your users and to improve your authoring workflow.

Read on to find out more about the features and surprises diagrams.net and other tools had in store for us at this meeting of the Continuous Documentation Regulars.

(8 minutes read)

Continue reading...
import('mycontent.adoc')

AsciiDoc content in a Single Page Web App

How to get the content on a website? Separating it from the technical stuff sounds like a good practice for distraction free writing and focused coding. Can an import statement do the trick to load the content from a markup file?

This blog post explores how content written in the markup language AsciiDoc can be used in a single page web application. It shows a minimal generic setup without using existing content plugins. The examples are based on webpack, NuxtJS and Vue.js. You can adapt the recipes in any project that uses webpack.

(10 minutes read)

Continue reading...
Logo Continuous Documentation Camp

Continuous Documentation Camp

Continuous Integration and Delivery is commonplace for software. Let’s benefit from the same principles and apply them to documentation as well: Keep it up to date, run automated tests, collaborate as teams, roll it to production seamlessly.

I planned for an un-conference, but planning was difficult due to the COVID-19 virus. The number of registered participants was too small. The camp is rebooting to find a new concept to attract more participants and to avoid an impact of the virus.

Continue reading...
ArchUnit Logo

Stopping Entropy with ArchUnit

So your team has agreed on naming conventions for classes and how to structure classes in packages. Last week you found out that a specific class is error prone to use. Writing this down in a Wiki will not allow for automatic checks. Tools that produce dashboards look nice at first sight, but will fall into oblivion soon.

My talk at Devoxx UK and BaselOne shows how to automate architecture rules and best practices as ArchUnit tests. It will compare ArchUnit with other tools to show limits and advantages of this approach.

Continue reading...
Asciidoctor Logo

Asciidoctor Deep Dive

AsciiDoc is a markup language for documentation. Asciidoctor is a popular implementation of a rendering engine for AsciiDoc.

Today I’m giving the talk at the JavaZone conference in Oslo. I post the code samples, the slides and a video recording of a previous talk at JavaLand here.

In the talk I share my experiences with Asciidoctor, tips and tricks and hints to style your PlantUML diagrams. I also show how to get most out of Asciidoctor PDF generation using templates and extensions.

Continue reading...
Micrometer Logo

Monitoring with Micrometer

Finally I’ve managed to publish the recording of my Micrometer talk at the JavaLand conference from March this year.

You can hear the talk next in Berlin (DE) in September and in Basel (CH) in October!

Read on to find slides, video (35 min) and upcoming talks on this topic.

Continue reading...
Book: Java by Comparison

Making the “Switch” for documentation

How are you handling documentation in your software project? Who is writing it, and is it up-to-date?

After reading the book “Switch – how to change things when change is hard” (by Chip and Dan Heath) I followed their advice and collect previous experience and new ideas how to make documentation work.

(15 minutes read)

Continue reading...
Writers Write @ Devoxx UK

“Writers Write” at Devoxx UK 2019

Devoxx United Kingdom 2019 hosted a documentation birds-of-a-feature (BOF) session: Dan Allen lead this session called “Writers Write!”, with Ixchel Riuz and Alexander Schwartz (me) being co-leads.

This is a write-up of the discussions and experiences we shared as a group. It takes a look at tools, challenges and trends in documentation.

(10 minutes read)

Continue reading...
The platform team supports multiple product teams.

DevOps: Fast, reliable and safe delivery

At the beginning of the century Nicolas Carr claimed that “IT doesn’t matter”. But today software delivers the services and products we consume, and every improvement requires changes to the software. Companies strive to test their new ideas faster and more reliable than their competitors. To do this, a company needs to re-invent its organisation, technology and culture for DevOps.

In our article in Informatik Spektrum Björn and me summarize who needs DevOps, how it works. We also detail the challenges and benefits.

(15 minutes read)

Continue reading...
Book: Made To Stick

Book Review: Made to Stick

When you write, write for your readers, they say. But will your readers remember it? Will they even read the article to its end?

Chip Heath and Dan Heath answer the question why some ideas survive and others die, i. e. why they are being remembered or forgotten.

(5 minutes read)

Continue reading...
CDN for simplicity

Hosting simplified by a CDN

Last year I moved my personal website and our Meetup’s homepage to Netlify, a content delivery network (CDN). I was astounded about the minimal steps necessary make it work. It simplified both the setup and the day-to-day operations for me.

This article takes you through the minimal, yet real world steps to set up the homepage of the Vue.js Frankfurt Meetup with Netlify.

(15 minutes read)

Continue reading...
Nuxt for fast websites

Nuxt: Making your website fast

You are looking for short loading times and high interactivity for your website? Nuxt got you covered: A JavaScript framework that serves a pre-rendered page for a fast first meaningful paint and then transforms the page into a full interactive single page

This post shows how to make Nuxt even faster with the webpack plugins imagemin, responsive-loader and postcss to minify images and CSS.

(10 minutes read)

Continue reading...
Book: The Tangled Web. A Guide to Securing Modern Web Applications.

Book Review: The Tangled Web

A good friend and colleague lent me this book.

Although the title “The Tangled Web” gave a different idea, the subtitle “A Guide to Securing Modern Web Applications” pointed to its security background.

It turned out to be a dive into the history and workarounds of the web!

Continue reading...
Observability Logo

Observability for Microservices

To be able to identify and analyse problems, applications in a microservice environment need to provide standardized information to enable efficient operations. This talk presents four areas that are part of observability: status information, logs, metrics, and traces.

Continue reading...
Book: Java by Comparison

Book Review: Java by Comparison

The full title reads “Java by Comparison - Become a Java Craftsman in 70 Examples”.

When I first heard of the book I was sceptical: Is there really enough common ground for 70 good code examples? Would the examples be the starting point of an argument if you would show them to a team of programmers? After a conference in Berlin, Simon offered me a free copy to read.

Continue reading...

Dotfiles for crossplatform projects

Whenever I start a new project, I like to check in configurations to Git, so that every other developer uses the same settings as I did. This also leads to more reproducible build.

This post summarizes the different files and their interdependencies.

Continue reading...
Microservices Article in Informatik Spektrum

Microservices - more than a hype?

For the German magazine Informatik Spektrum I wrote an article capturing the current ideas of microservices as an introduction.

It’s based on my project experience over the last two years. A free online-version of the article is available as well!

Continue reading...
RSS Feed