Rather than diagrams as code what does code as diagrams offer?

Living Documentation — Part 3

You often hear the phrase “diagrams as code” referring to using a text editor to write some code that can be parsed to create a diagram rather than using a graphical editor and UI to create a diagram. If however, you parse real source code to create a diagram then you are reverse engineering it. So what value does “code as diagrams” give us as engineers?

The simplicity of the structure according to Monet

The evening scene in the painting by Monet of San Giorgio Maggiore At Dusk shows the outline of the building, with no details on the building just a dark shape. A simple graphical representation…

Don’t think you have cracked software quality just by using SOLID

What is good software?

Having interviewed a selection of new developers for a recent role I had time to reflect on how they all handled two questions, what is SOLID? And what makes good software?

What is SOLID?

Without exception, they could all explain what SOLID principles are and give a reasonable description of what it means. But when asked why? then the answers started to fall away. It became clear they have been taught a formulaic way to write software to achieve a goal, and they think SOLID is the goal, not the journey.

“SOLID is not the goal it is part of the journey”


A thorough introduction to Living Documentation packed full of examples and tips

A book on continuous knowledge sharing by design by Cyrille Martraire

This is a solid reference book, with a substantial content of 480 pages in a hard back cover. It has a picture of the pipes from the Pompidou centre in France on the cover, which is relevant due to the colour coding of the types of pipes which is an example of self documentation. Cyrille Martraire is a CTO and speaker at conferences on various aspects regarding software development. There is a lack of material in this area so this is a welcome addition to the bookshelf. It heavily references DDD Domain Driven Design, BDD Behaviour Driven Design and Java…

How to self document your code for the next poor person who has to use it, fix it, or sell it

Living Documentation — Part 2

Self-documentation — is documentation in a suitable form, typically label, signs, or simple instructions embedded, attached, or nearby to the device. This allows the device to be used, operated, changed, and repaired by following the instructions without having to hunt for some other form of documentation.

For those of you that think DOORS is some sort of new operating system or methodology then prepare to be amused. I thought it would be fun to explain what self-documentation is, and various styles through examples. The easiest device and familiar to us all is a door. The standard operation and use of…

Part 1


In this first article I want to set the scene by outlining what living documentation is, and the types and flows of knowledge in the engineering process. Future articles will cover currently available tooling and options.

So let's get started and cover some basics to all get a common understanding on:

  • Definition of Living Documentation
  • Forward and reverse engineering
  • Maintenance and customer documentation
  • Design evolution
  • History of living documentation

Definition Of Living Documentation

The key elements of living documentation are:

  • Living — it is up to date and reflects the current state of the software
  • Documentation — it is a collection of descriptions regarding…

Don’t gamble when solving software problems

How to use root cause analysis (RCA) and a hypothesis to become the ultimate software warrior.

Having observed lots of software engineers attempt to make things better by gambling on a gut feel, I wanted to share some observations and great tips that can make you stand out by tackling things in a structured and professional manner.

“When you want to know how things really work, study them when they’re coming apart”. — William Gibson

Traditional Strategies a.k.a. Bodges

There are a variety of strategies I have seen people use and often the issue appears to be magically be fixed and the engineer hailed a hero. Even though they are not sure what they touched that has made a difference…

As a manager when you start to feel the pressure of deadlines, an overwhelming number of tasks to do, or an avalanche of emails then you need some help. Keep reading for some handy tips for managers on the critical path.

Two key tips that are useful, and perhaps controversial so may only be useful when the pressure is really hot are:

  • BLUF email formatting style — which may be interpreted as too direct and hence blunt for your organisation. …

The entire world of outsourcing summarised as an easy to use picture

All the information you need on a single page to start outsourcing in 2021

Sometimes you just need all the information in a quick and easy to access format, so we have made The 2021 Essential Guide to the Outsourcing Landscape on a single page to help you.

It covers everything you need to know about:

  • Outsourcing models — onshore, nearshore, offshore and hybrid.
  • Time-zones and the offsets from GMT for some key outsourcing locations around the world.
  • Project documentation — functional specification, non-functional requirements, contracts, proposals, supplier assessments.
  • Supplier selection — specialist skills, compatibility with your business, flexibility.
  • Team growth– internal, external, hybrid options.
  • Approach — time and materials, fixed cost, staff augmentation.

You are quietly doing your job managing one or more development teams when you get an urgent call. The project needs to be done super quick as the client has accelerated needs and this is now the number one project in the company. This is the point you regret not being more prepared, you have no list of go-to favourite and trusted suppliers, and the pressure is on for quick results and a big success. What do you do? Keep reading to learn everything you need to know about using the PDCA model to improve finding an outsource supplier.

Everything you need to know about using the PDCA Model to Improve Finding an Outsource Supplier


Greg Billington

Technology Director | Passionate about management, development and helping technology teams outsource software projects successfully | https://outsource.dev

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store