Documentation, What is it Good For?

If, like me, you grew up in the 1980’s with Frankie Goes to Hollywood you’ll instantly want to reply to the title question with “absolutely nothing!”. You may also pick the same answer if you misread the Agile Manifesto as saying that we should “create working software, not write documentation”.

Of course everyone knows it really says that we should favour “working software over comprehensive documentation”, and yet it feels as though many are replacing the word “comprehensive” with “any”. Whereas before we tried to get out of writing documentation because it was boring (hint: that’s the fault of it being comprehensive), we can now use the Agile Manifesto to reinforce our opinion that we should go full steam ahead and only write code because documentation is either pointless or of very little value.

The YAGNI Argument

One of the reasons documentation is seen as having very little value is down to the fact that apparently “no one reads it”. There is more than a grain of truth in this argument and it’s something I’ve touched on before in “The Dying Art of RTFM”. Also, as is probably apparent from the “Pen & Paper” article in my Toolbox series for ACCU’s C Vu, I like to make notes in a log book about the work that I’m doing as I find them useful later.

Hence my premise around documentation, and this has always applied equally to writing tests and tools too, is that if I’ll find it useful later I suspect that someone else will too. Therefore, first and foremost I write documentation for myself, and that gets us over the YAGNI hurdle. So, even if nobody else is going to read what I write, the fact that I’ll probably read it again is good enough for me to consider it worth the effort (and therefore it has at least some value).

This blog is a prime example of such an outlook. I have no idea whether anyone else will read anything I write, but what I have discovered (like so many others) is that the act of writing is in itself valuable. Naturally one must be careful not to compare apples and oranges as using the company’s time to write documentation has a definite monetary cost compared to the cost of writing this blog which would be mostly valued in time instead.

Certainly in my earlier days of documenting aspects of a project, I didn’t know what kinds of things were worth writing up and I almost certainly still wrote way too much up front. In part what I wanted to write was not just about the topic itself, but often the rationale that lead to the decision. I felt that without the rationale you wouldn’t know if the documentation still held any value in the future as what lead you to that original decision may no longer be valid, consequently you’d know when it was time to delete or rewrite it.

Keep It Real

When I first read the term “comprehensive documentation” what came to mind was one of those massive enterprise-grade masterpieces that has at least half a dozen introduction pages covering the table of contents, version list, signatories, disclaimer, etc. If the actual content doesn’t even start until page 12 you are pretty much guaranteed that no one will ever read it. Also making use of fancy technologies like OLE so that any embedded content is subject to the whim of the Network Gods is also not going endear people to it.

I, like many other developers, like simple documentation – simple to read and, more importantly, simple to write. The barrier to writing documentation should be low, really low, so low that there is very little reason to not do it. By taking away all the superficial formatting, e.g. using Markdown, it’s almost impossible to get bogged down with playing with the tool instead of producing what matters – the content.

Hence my tool of choice is a simple wiki. Whilst storing text documents and any simple images in the source repo itself is better than nothing (or going way over the top) GREP is just a little too crude for searching, and having page navigation just makes life that little bit more joined-up. I’ve find that GitHub makes this format very usable, but what would make it better is if there was even a half-decent, simple Markdown viewer for Windows [1].

The great thing about plain text formats is that you can still use your favourite text editor and most support a spell checker plugin to at least avoid any obvious mistakes. Trying to read badly written prose can be jarring for the reader, but I’d still prefer to have the content than not at all as someone can always fix the little mistakes when it gets updated. With a browser like Chrome (which comes with a built-in spell checker) even the basic edit boxes used in online wikis is good enough [2] for creating most content.

Naturally plain text is good for the written parts but sometimes you need an image, such as a diagram. ASCII art can work for a very simple picture but you really want something just a little bit better. My current favourite online tool is draw.io which makes it really easy to create simple, effective diagrams. You can then generate a .PNG image which you embed in the page and also export the diagram as an .XML file for attaching (or checking-in). This way anyone can edit the picture later as they have the source. Personally if the diagram would take a long time to recreate from scratch then I’d question if it was too detailed in the first place.

Common Themes

Most of the documentation I write is not about the features of the product – you have the stories, source code and tests to tell you about that. The things that I tend to write up are the aspects of the process the team uses and many of the little things that we perhaps don’t do or consider every day but act as examples of how some development or support tasks could be done.

Basic Architecture

As I mentioned earlier I feel one of the most important things the team can jot down is the rationale around why things are the way they are. Architecture is a prime example of where knowing how you got there helps you understand the forces that drove the decisions – even if its that no conscious decision was ever made.

There is a slightly meta aspect here too as I like to start by linking to two sources on why I’m even doing it: “Record Your Rationale” from 97 Things Every Software Architect Should Know and Michael Nygard’s blog post on “Architecture Decision Records”.

Generally speaking I’ll only create a simple top-level architecture diagram to show the basic footprint and provide a quick description of what the major components are. This usually provides enough to orient someone and can act as visual clue should you be chatting to someone outside the team about the system [2].

Team Details

I also like to create a simple page that at least lists the team along with some of their contact details. When all you’re given is a cryptic login like THX-1138 it becomes a pain trying to find out who owns a file or which developers are hogging the two RDP connections to a Windows server. It also provides a place to put a mugshot and some other details which can provide a more welcoming feel to other teams; I prefer to belong to a team that openly promotes collaboration rather than tries to hide behind a ticketing system.

Operational Tips & Tricks

While we might wish that our systems are perfect, have 100% uptime and never do anything weird, that just isn’t a reality. The idea of having a knowledge base for the support and operational aspects of a system is nothing out of the ordinary, but we need to balance documenting quirks with just getting on and fixing the bugs that cause regular support issues.

For example although an in-house system should be able to come up in any order there might be a preferential one that just makes life easier. Also any post mortems that have been carried out are useful to document so that not just the team itself but the whole organisation can learn from accidents and failures.

Development Guides

Operational notes are probably a fairly obvious artefact but I like to do the same for development tasks too. In an enterprise setting you often find junior developers being given what are seen as “simple” tasks but no guidance on how to do it. You can’t automate everything and sometimes they need some background knowledge to help them along [3].

I’ve also found that during development you bump into various quirks either around the toolchain or dependencies that are worth making a note of. For example Visual C++ developers used to run into pre-compiled header build problems with a drive mapped using NET USE that didn’t happen with SUBST.

One-Liners

On my desktop I always have a text file called “one-liners.txt” that I use to store those little command lines that come up time-and-time again at each client. They often revolve around build or support queries, such as parsing data out of log files or test data files. If the command remains useful it can be “scriptified” but before then I like to share where I’m up to so that other developers can learn how to compose the standard tools (or PowerShell cmdlets) to solve the smaller tasks. Many Windows developers aren’t comfortable at the command line and so I think this is a great way of showing them what they’re missing out on. Once a task gets turned into a script it becomes opaque and just “the solution” whereas I find the “raw pipeline” teases at another, different world of programming.

Links

Whilst StackOverflow probably caters for a lot of the Q&A these days that I might historically have documented, sometimes the error message and the solution don’t always immediately tie up and so I like to fill that gap by having a simple Q&A page that links to SO but with the actual error they’re likely to encounter.

Junior developers often don’t know how to separate the wheat from the chaff and so links to articles of special engineering interest, blogs themselves of notable luminaries, essential books, etc. are all worth capturing. Part of the rationale that drives a solution comes from the ambient knowledge of its team members and so therefore knowing what shapes them can help understanding of what has shaped the application.

Summary

Contrary to what you might have heard, not all documentation is waste. In a stable team where there is plenty of opportunity to learn from the code and by pairing you can get away with less, but there are still going to be things you want to remember or share with your future team mates.

Don’t set out to write War & Peace – grow it organically. If you’re not sure if it’s worth sharing it’s better to stick a crude one-liner with a simple note on a page, which someone else can then embellish and refactor, than to never do it at all. Keep your investment small until you get a feel for where the true value lies.

One of the tasks I like to include as part of the “Definition of Done” is around documenting anything that might be of interest. This means that writing documentation becomes just another part of the development of a story, like writing tests. Most of the time there is nothing to be done but at least documentation then becomes part of the conversation around every feature.

Finally, don’t worry if some people don’t seem to read what you write, it’s unlikely that it’s undiscoverable or abhorrent, it’s probably that they just don’t work that way. If whatever you’ve written is valuable to you then that’s a good start, hopefully your current and future team mates will find value in it too at some point when they go looking for answers [4].

 

[1] For some reason everyone wants to be a Markdown editor, but nobody wants to be a simple viewer and sadly the Chrome extensions aren’t friction-free either.

[2] If it’s a longer conversation then a whiteboard session is probably more suitable than staring at a static image.

[3] I once wrote a guide called “Efficiently Merging ClearCase Branches” as developers kept getting the order wrong around bumping the label in the config spec and merging the changes. This created huge amounts of noise and in the repo through unnecessary versions.

[4] On more than one occasion it wasn’t until after I had left a client and then met up for drinks sometime later that I got thanked for leaving behind useful notes. Hearing that kind of feedback makes it all worthwhile.