The Why and Why Not Of Documentation

FAIL stampMy core pet peeve of the last 10 years is the lack of documentation I’ve encountered with Software Projects. Sometimes it’s as the consultant that’s called in after someone already charged a lot of money for a substandard job. Sometimes it’s that legacy project that sticks around through generations of developers who leave a company. Sometimes it’s the “we don’t have time” factor.

Documentation is a value-added part of any software project for a variety of reasons:

  • Reference: The ability of software engineers involved with a project to look back and see why things were done the way they were, and to allow for knowing the limitations and potential of a project.
  • On-boarding: Bringing new software engineers up to speed quickly without having to bounce around the company finding answers.
  • New Projects: Proper documentation of old projects, including estimates and other data, is of great use for estimating similar projects. (Project Management and Business Analysis)
  • Complicated code reviews are simplified.
  • If someone gets hit by a bus, someone else can take over. Quickly.
  • Legal: If a project is supposed to meet certain requirements, those requirements should be traced to the actual implementation.
  • Teams: Proper documentation in an Agile or DevOps process allows team members to see what others are doing in similar areas of code, and allows easy identification of problem areas quickly.

These are just some of the reasons documentation is important. More often than not, I’ve ended up writing documentation at different companies because it simply did not exist before.

Why didn’t it exist? Here are the standard excuses:

  • No Time: We didn’t have any time to write the documentation because we’re busy working on the next thing!
  • “Me no write so good”: Fair enough, but there’s only one way to get better at writing.
  • “It’s not my job, man”: Erm – no. Documentation is a part of software engineering. A big part.
  • We don’t know how to organize it: Fair enough. Spend some time and figure it out and implement it.

At the base of all the excuses are 2 things that are really simple:

  1. Software Developers generally don’t like writing documentation.
  2. Management fails to have developers write documentation.

These 2 things are understandable, wrong, and amazingly easy to deal with if a company wants to.

Writing and Tech Documentation.

cubiclecreativity

The tough part about good documentation is that everything has to make sense. All the stuff has to ‘line up’ along the user stories for the use of the documentation.

There’s the high level story and the lower level stories that make the high level story work – and those same low level stories can have multiple dimensions of their own if written conscientiously with modern tools.

Documentation is usually dry and boring. Dry and boring is great reading for those who read the DOS manuals and Unix manuals end to end (I did), and you can amaze other people with how much you can’t be understood when you talk. That’s where the social engineering aspects of documentation come into play. Or, as writers would call it, writing. The documentation has to be sticky in the marketing sense, such that when someone reads it, they remember it. For the software engineering side – the technical side – less so. On the user side, it has to be… usable.

We’ve come a long way when it comes to our capacity to organize documentation online1. The actual writing, though, has to lean toward a SEO type of writing – repeating key phrases and using possible words and phrases that a user might search for. This requires understanding how a product is expected to be used as well as how it might be used. The latter is not as important for the planned use, but is important for disruptive use cases that might pop up on the radar and allow a business to leverage quickly.

Simply put, good technical writing allows for what is planned, and enables potential uses1.

1 Something I’ll be writing about some more this week.