The Art of Technical Documentation

11/06/22 08:02 Filed in: Industry
Why do you document stuff so solidly? Do you think people read all of it?

====
I got asked something the other day, that while a simple question, took me some time to ponder and fully answer. Why do I produce so much documentation for stuff?

First, some context. I spend most of my time designing, deploying and even sometimes - operating - mid-market IT systems. Mostly Office365 and Unified Communications areas, as I find them the most interesting. By mid-market I tend to focus on the up to 10k seats area. Mainly as I find that's a size that's manageable and you spend most of your time actually doing the interesting technical stuff rather than lots of incremental minor things due to risk management. I have worked on big stuff - some of it properly big (400K+ users) - and while that has it's own attraction and interest, the mid-market I find more interesting.

Over the years I've developed a solid strategy for dealing with complex systems, and managing change. I don't mean the formal change management processes - they of course have their place - I mean how *I* manage what I'm doing, how I establish the outcomes I want, and how I get there. This is the bit that tends to produce a lot of documentation.

Let's imagine we have a requirement to implement a reasonable amount of change for a system on a remote site. My documentation process will follow this methodology:

  • The why and the what. Here it's a brief to ensure that everyone understands what's being asked for, why it's being done, and what the expected outcomes are. This has been vital in catching some misconceptions/differences between people.
  • The how. This details how I'm going to achieve what is being asked. All touch points, impacts, expected outcomes etc. Also includes how we roll back. This is often included in the change management process.
  • The doing. What happened when we implemented? This is great for lessons learned and for future similar projects.
  • The final state. Sometimes referred to 'as is' documentation.

This feels like a lot doesn't it? It really isn't in the real world. I've been following this process for so long that it's second nature to me. It has some very specific pay offs too. I have a complete audit trail of what was asked for, what was agreed, and what happened when we did The Thing. That's come in very useful in the past.

Do you know what's really important about the process though, that I think is often missed? This process helps me vastly reduce risk in increasingly highly complex systems. This has been a developing area in the world of technology (Complexity Theory), with a key part of it being Systems Theory. Understanding how one system is dependant on another, and affects several others - it's challenging.

This documentary process then - for me - is a lot more than just the documentation. It's a process of fully understanding a requirement, establishing how we get there, and then helping the people running the systems also have a handle on it after we're done. The process is arguably just as important - if not more so - than the documentation itself.

This is the bit I find interesting, and it took me some time to explain.

The pay offs from this process are several. From a freelancer perspective, this makes me reliable. Typically I achieve what I am being asked to achieve, and usually in the manner we've planned and agreed. Another key pay off, is that it makes me look at the technology I deal with in a lot more detail than is perhaps necessary for specific items. That always aids understanding, and that is never a bad thing in technology.

Anyway, a simple question, not such a simple answer. Writing good documentation is also challenging in the technical space as you have a wide range of readership to consider, but that's a subject perhaps for another day.

blog comments powered by Disqus