Why user documentation is critical

By Andrew Clifford

Without complete user documentation there are almost certain to be holes in your system.

One of the sentiments of modern programming is that code that is not accompanied by automated regression tests does not exist. I would extend this and say that functionality not accompanied by effective user documentation does not exist.

We have a lot of technical documentation about our Metrici Advisor service. However, we do not have complete documentation for people who use the service, particularly for those who use it to develop new solutions.

To plug this gap, I have been writing tutorials for colleagues and partners who are involved in solution development.

This took me longer than I expected. I kept finding things that were hard to explain.

I got stuck on the very first tutorial, trying to explain the basic concept behind Metrici Advisor. Internally, it has a store of objects we call nodes which are accessed through unique URLs. But that is difficult to explain. To make it understandable, I had to turn it around and describe Metrici Advisor as being made up of web pages, each of which is represented internally by a node.

I got stuck again explaining metadata. Each node is defined by a node type which is itself a node. But that is too abstract to explain simply. I found I could explain it better by presenting it as a series of layers: a solution layer, a solution type layer, a developer layer, and a system layer.

Then I got stuck trying to explain user groups. Metrici Advisor can support any number of user groups, which are used for setting permissions, and which can be arranged in different ways to achieve different effects. But that is too abstract. I decided to simplify it so that each account has a main user group with all the account users in it, and that additional user groups can be created to grant permissions to subsets of users in the account.

It got worse when I tried to explain how some of the structures work. Internally, we use an optimised triple store, which is a very abstract concept. We had to invent a formal diagramming notation to explain some of the structures in a consistent and concise form.

With great relief, I have completed the first dozen or so lessons in the tutorials, enough to get colleagues and partners up and running. But as well as creating training material, the process of having to explain it has really tightened up the solution in a number of areas.

• We have found simpler ways of thinking about the structure of solutions.
• We have worked out how to split solutions into distinct layers with different responsibilities.
• We have standardised how we manage users in accounts.
• We have developed a formal notation which we can use in solution design.

These are not just devices to teach people the system. Thinking this through has given us new ways of defining solutions and new ways of managing the service, and filled previously unseen holes in our thinking. It was only the need to write the documentation that prompted us to complete these parts of the solution.

Subscription