Writing good documentation

Last week a friend called me and asked for help to put together some furnitures for his newly bought apartment. Together we tried to follow the user manual and as the time passed the more frustration we felt. Perhaps our clients feel the same way as we did when they use our systems? Somethings that feels clear to us (the builders) can seem like a impossibility for the consumer, the client.

With this analogy in mind I realised how important writing good documentation is. I also started thinking on how we can improve existing documentation and how to write it better for the future.

There are two kind of documentations I believe should be written, one for the consumers (the clients) and one for the developers.

Documentation for the consumers.

So, how can we best teach a client? For one we can have a user manual, introducing the system and the things clients will work with on a daily basis. Answering simple things like login, writing content, but also how the system works and should best be used. We use Drupal (a CMS) at work and they have a user manual that we translated and use as a base to introduce to the clients the basics of the CMS.

However many of the systems that are being developed are different than the core install and might be slightly different. Therefor if the CMS manual does not match that product, it should be adjusted to be so.

  • How is the system used best?
  • What are the limitations?
  • Workflows typical for the solution

Many of these questions has already been partly (or fully) discussed during sprint plans and discussions with the client on what you actually are producing. Putting them down in text, will help later on.

One of my colleagues also does video tutorials that are much appreciated from the clients. These videos are made in a local environment of the system that's later shipped to production. Producing these videos as new features is shipped and how they are used is something I believe can be really useful. Videos also has the pro's of the consumer being able to see how a workflow works from start to finish and jumping back and forth. In text it's a bit more work and harder to do so.

We also like to invite clients to come over for a couple of hours to be introduced to the system face to face and being able to answer questions they might have right of the bat. These are often appreciated and I believe this might be one of the best ways to learn the client how to work with the system. This might not always be available to do, but if so, consider doing a Stream through something like Google Hangout or Skype. Recording these and making it available afterwards so we can look back is also an good idea.

Documentation for the developers.

Every once and then we have to go back on these medieval systems that was written years ago. Most often it's a bug or even a new feature that has to be addressed. These legacy applications often tends to contain bad decisions and smelly code that is really hard to maintain. Perhaps the employee who first created is no longer with us and those who were around doesn't have a clue on what's going on it. These things are scary to work with, things break easily and there are no tests to verify that the changes you did broke something else in the system. Documentation for developers are also important and stuff that makes sense now will most certainly not in one year or more later on.

What about refactoring the code? Well refactoring and improving existing code is not always an option. We wish, but there may not be an budget or interesting in doing so.

To prevent these things we introduced Tech leads at work that makes sure documentation exists and is available to answer questions about the system when needed. The questions vary, but we've set up a pretty decent template:

  • Project details
    • CMS/Framework used?
    • Language, language version?
    • Web host?
    • Teach leads?
  • Introduction, small introduction on what the project is and what it does.
  • Startup, how do you install and get the project up and running on a local machine
  • Things to really know about this system
  • System structure
  • Production environment and backup routines
  • Things to verify works after an update (unless we have tests)
  • Sprint descriptions (what we did and were done in latest sprints)

I believe one of the most important thing is the Things to really know about this system. That is really helpful, especially if the system does something like pushing tweets, sending emails or something else that you have to be aware of. We kinda try avoiding these things and making sure development environment is safe to work in, but in legacy or projects that we've taken over it's not always for granted.