Media is any form of publication or distribution that contributes to, distributes or otherwise partakes in. Currently there is:

Articles are canonically published on the website, but can be syndicated on any provider that allows a canonical link back


Long form (160+ character) publications must be allocated a canonical category from the following:

Type Description Publication Stream


A review of a new or experimental technology, not yet used in a production environment.


Case Study

A review of a previous technical or process intervention focussed on return on investment

Medium, Website

Technical Analysis

A general description of a technical implementation across many systems

Medium, Documentation

Deep Dive

An in depth discussion of a given technical problem and solution



A discussion of the underlying beliefs behind the software development

Medium, Website


General Process

When writing a (long form) post, the process is as follows:

  1. Write the post up & publish it to

  2. Verify the content against the Hemingway app

  3. Wait ~24 hours

  4. Re-read the content

  5. Publish the content to the distribution network

A template for writing the article is below:

categories: []
// Uncomment one:
//  - "Labs"
//  - "Case Study"
//  - "Technical Analysis"
//  - "Deep Dive"
//  - "Philosophy"

// Date in the form of "1970-01-01"
date: __TODO__

// A description used in search results, social media tags
description: "__DESCRIPTION__"

// How the URL should appear
slug: "__this-is-a-url__"

// A list of things that this article should talk about
// Try and pick ~ 4 tags. The list of previously used tags is at the following URL:
// When syndicated, the category should be an additional tag.
  - "__TAG__"
  - "__TAG__"
  - "__TAG__"
  - "__TAG__"

// The header of the article
title: "__TITLE__"

// What GitHub issue the article is tracked by
github-issue: 11

// The path to images suitable for use with the article
// The images work best at 1000x420
  - "/images/headers/architecting-a-software-system-for-malleability.png"

// Who contributed to the article, written in the order of their contributions.
  - "Andrew Howden"

== __TITLE__

// Content

Social Media

Messages should be written approximately as so:





  • Iteration: A notation like [New], [Via Archive], [Repost], [Revised] denotes why the item is being posted

  • Title: The article title

  • Description: A description of the articles contents

  • URL: The URL to the article.

The terms used in the iteration mean:

  • New: The article has never been published via social media before

  • Repost: The article was recently published via social media, but not in this timezone or day

  • Via Archive: The article is an older post

  • Revised: The article is an older post that has been rewritten with more up to date content



Admonitions are used to draw a reader to a particular, otherwise unspoken tip, caveat or warning. In asciidoctor the syntax is as follows:

NOTE: This is a note

The supported admonitions and their intended usage is as follows:

Clarifications. For example: "This page is the styleguide and employs demonstration content"
Advice. For example, "TIP is best used for the sort of additional, non critical but perhaps helpful advice"
A warning that clarifies a thing that might not otherwise be expected

The following are available, but not recommended for use.

Content that is the "main" point of the article.
A stronger caution


References are used to illustrate from where information came from. In asciidoctor the syntax used is:

This is a sentence. It has a reference which is dope^cite:[citation.reference]^

At the bottom of the article a section should appear as follows:

== References


As much as possible, content should be referenced with links to the third party resource or material that is referenced. For this site, references are stored globally in the bibtex file.

Do not use links to reference material. Links do not transfer to other media (such as print) well and do not provide about the information at a glance within the article.
Found a bug? Got a correction? You can edit this page on GitHub