Documentation is like sex: when it is good, it is very, very good; and when it is bad, it is better than nothing. - Dick Brandon

The Problem.

One of the strangest things about the software industry is just how poor documentation is. A very strange situation, because a software engineer’s literal job is to explain to a computer (via source code) how to do a given task. You’d think that that would mean those same software engineers were naturally adept at passing similar information to their friends/colleagues.

There is a movement within the industry to not document things. A common refrain is that “comments lie”, a problem where a comment in code isn’t updated when the code changes. I’ve also worked at companies in the past that have literally forbidden me from commenting in code why the code was doing something.

Knowledge transfer is critical.

It’s in the companies interests to not have brittle knowledge repositories (if someone is [hopefully not, of course] hit by a bus on their way to work, all that knowledge is gone). It’s in the leadership’s interests to have their reports know exactly what is being discussed, and why, saving having to repeat themselves, and, crucially ensuring that what is being asked for is actually delivered (very much the theme of Domain Driven Design’s Ubiquitous language!). It’s in the interests of the people reporting to the leaders to know exactly what’s being said, why it’s being said, and what is expected of them (and what to watch out for!).

There is no downside when knowledge is shared in a way that works for everyone involved.

That being said, passing knowledge isn’t easy (the catch is the need for the knowledge transfer to work for everyone involved). Comments on why a piece of code does something is helpful, but it doesn’t tell you the architecture. The architecture doesn’t tell you how upstream and downstream systems interact with your system. Non-technical users have different needs to technical users (with respect to documentation) and the level of detail needs to suit different requirements.

Not only that, but the mere mention of some documentation technologies (UML) is enough to shut conversations down and have people walk out of the room (literally).

The Solution.

This weekend I am having my second try with PlantUML - which I can honestly say is nowhere near as painful as UML of old (but I have not yet got to the point where I have documented the system I am working with).

And, to address the fact that there are multiple levels of needs for the documentation I am following the c4 model which breaks documentation into 4 categories, each more detailed than the last. * Context (What external systems does my system interact with) * Container (What deployable units/containers exist within my system, and how do they communicate) * Component (A loaded word in SWE, but what components make up each container) * Code (How is the code in each component architected)

Summary.

Armed with the tools I intend to make diagrams that are readable by different people and pass to them the knowledge that they need to do their jobs,making my job easier.