Documentation

In order for any bit of complex software to be better understood and effectively utilized, documentation must be made available to the people who will use the tool. Unfortunately, documentation is the least favourite task that faces every developer. I can count on one hand the number of full-time software people I know who actually enjoy putting the code editors away to instead write complete sentences. There are automation tools out there that will try to write the documentation for you, but these can only go so far. At the end of the day, the best author is going to be someone — or a collection of someones — who have a good understanding of the system … which can certainly be a problem for tools that are created by one or two people.

At the day job I'm fortunate enough to be in a position where I get to make new software every couple of months. These are tools that don't exist one day, then spring into existence 20 minutes after a meeting that sanctions their creation comes to an end. A lot of the tools start out small with just three or four functions that are relatively intuitive to anyone who has worked for my employer a couple of months. However, as people begin to use the simple system and ask for "just one more thing", the software becomes more complex. The rules become more opaque. The emails from people asking how to do something becomes unworkable. By this point, documentation is not only needed, but late.

Near the end of last year I was given the opportunity to create a piece of software that would be used by colleagues all over the world and integrate with our HR systems. After a couple of discussions with the project owners it became clear that documentation was something that couldn't wait until later, it needed to be part of the development cycle1. The HR department wanted a Word file that could be updated easily and sent out as a PDF to everyone who used the system. I balked at the idea and suggested that documentation be built right into the application, complete with screenshots, videos, and links to the pages being discussed. The management wasn't keen on the solution initially, but they quickly saw the benefit once the feedback started coming in. People were actually reading the documentation that was going up, and they thanked the HR managers for making it happen so quickly.

Score one for preparedness.

In addition to this documentation, though, is the developer documentation. This is generally something that doesn't get seen by people but, because this HR project is owned by HR, some key people have access to the GitHub repository where the source is kept. These people have been reading the commit messages, Wiki pages, and Issues, and they're quite impressed with the level of detail that goes into the internal docs.

Writing a great deal on GitHub is nothing new for me, as it's sometimes necessary to have a single place where the rules and reasoning behind certain design decisions are stored. To help future me, I try to include screen shots and lists of reasons for why some functions or classes were created the way they were. If something is particularly complicated, then the messages in the commits will be a little more colourful than the dry words found in the Wiki or supporting Markdown files. This is something I try to do with all of my applications, as most of them start out small and simple, then quickly start battling scope creep as more functionality is built in. There's just one problem, though: there's almost nothing (documentation-wise) for 10Cv5 in GitHub.

The vast majority of the notes for v5 have been written to A5-sized notepads and I'm not yet 100% sure how this information will get shared with the world in a readable format? Scanning with OCR could work to a certain degree, but these notes are not always written with complete sentences (or grammar) in mind.

Documentation for v5 is slowly being released with more going out every few days. Regardless of how many people use the system, having it documented will make it easier for anyone to understand how and why it does what it does. Had I been a little more proactive with the v5 documentation like I have been with the day-job projects, then there would likely be less missing from the platform2. Fortunately there is still time to remedy this issue.


  1. Generally this is the rule for larger organisations.

  2. One interesting thing that I have noticed is that by writing documentation for the system, I get to revisit the core functionality with a semi-fresh mind. If something doesn't make sense when I'm trying to write it down, then that's a pretty good indication that something can be improved.