documentation

The Power of the Walk-Through

Matt HayesLeave a comment
Looking down through the trees in Wellington Botanic Gardens as the sun sets over house-clad hills in the distance

There are many cognitive biases waiting to trip us up. Sunk Cost Fallacy, The Curse of Knowledge, Confirmation Bias, the list goes on[1]. A cognitive bias is a common flaw in our thinking that leads to an irrational judgement or decision.

I think I’ve found a new cognitive bias.

My experience tells me that people fail to read documents, even when they know they should and would benefit from doing so. Yet, despite this, I still hold an unfounded expectation that when I write a document, people will read it. I suspect others do too. Is this a cognitive bias?

Let’s look at the underlying issue:

Continue reading →

Experimenting with NiFi

Matt Hayes2 Comments

Apache NiFi (see Introduction to NiFi) is a free open-source tool for managing the flow of data between systems.

In this second post, we build a working NiFi demo, with a couple of simplified use cases, allowing us to see it in action and learn by experimenting. The demo runs in a Docker container and comes with batch and real time event DataFlows and basic test data.

Continue reading →

Other Uses for PlantUML

Matt HayesLeave a comment

I like PlantUML and the whole diagrams-as-code ethos, where diagrams auto-generate from source code in the same repo.

Sure, the way PlantUML lays out objects and lines in free-form diagrams is arcane – try drawing anything beyond a few components, and you’ll end up in a pitched battle with the layout engine, resulting in a mediocre diagram in a state where you’re afraid to make changes, lest the lines and placement go all wonky (again).

Thankfully, things are better when using PlantUML to produce opinionated diagram types, where the layout rules are predetermined, such as sequence diagrams, mind maps etc.

I got to thinking – could I use PlantUML in the workplace, outside traditional architecture/code documentation, to help visualise other things? Only one thing for it – give it a go…

Continue reading →

Diagrams as Code (PlantUML)

Matt Hayes2 Comments

header-image

Is a picture really worth a thousand words? What if that picture was a diagram?

A colleague recently introduced me to Diagrams as Code, using PlantUML, and in this post we explore the concept of diagrams-as-code, and how to use PlantUML.

Diagram Methods

Let’s start with some background. Diagrams should engage their audience, informing them and encouraging collaboration. Understanding the knowledge and needs of your audience is critical to creating a successful diagram.

We adjust the diagram to suit the audience, using different views of people / process / technology to inform and engage them. Often, we will draw multiple views of the same system to suit the needs of different audiences, as per Figure 1.

Multiple Views of the Same System

Figure 1 – Example of Multiple Views of the Same System to Suit Different Audiences

Continue reading →

What is a Network Traffic Flow? (Part 3)

Matt Hayes1 Comment

banner_network_flow_post_3

Network traffic flows (flows) are useful for building a coarse-grained understanding of traffic on a computer network.

Following on from What is a Network Traffic Flow? and What is a Network Traffic Flow? (Part 2), this third post investigates flow metadata, how it adds value to flow analysis, and how to record and transport it. This is the good stuff, where flows become useful…

figure1

Figure 1 – What this blog post covers

Continue reading →