[By Matthew French] When I was renting a piano for my daughter recently, I found an obvious spelling mistake in the lease agreement. This provided great amusement for the rental agent. He had been using the same contract for 20 years and I was the first person to point it out. Unfortunately for me, it was a bitter reminder about one of the key problems of documentation — nobody ever reads it.
It is hard to describe that feeling of tired resignation I get everytime someone decides that documentation will solve all the world’s problems, and especially those technical ills that are the reason people believe documentation is needed in the first place.
Now before you write me off as a cantankerous old software developer, I have to confess I love good documentation. In the days before the Internet, I would relish a new technical manual — I would scan it for clues, useful hints and anything else that would help me better understand how something worked. Much of what I know about computers today was learnt browsing through obscure and sometimes obsolete manuals.
But then I met my match with Novell Netware 3.11’s documentation. It comprised dozens of manuals that took up an entire shelf. Alas, apart from one lonely spiral bound reference booklet, it seemed to be free of any useful content. It proved to be an early example of what documentation would become — an exercise of quantity over quality.
Since then, of course, the world has changed. Computers mutated from being the exclusive domain of the geek to something that is a key part of our everyday lives. At the same time, rising complexity meant it became much harder to document all the features in a way that people could find the information.
Alta Vista, Yahoo and finally Google meant the need for reading comprehension was replaced by the skills needed to construct queries and quickly to identify which search results were relevant.
These changes affected the nature of documentation, but shouldn’t have affected quality. The biggest culprit in the demise of technical documentation was the ascension of Microsoft Word. Giving Word to everyone was like putting a top of the range digital single-lens reflex camera in the hands of a two-year-old. Suddenly anyone could produce a document that looked great, but lacked substance.
Of course, word processors existed long before Microsoft Word became ubiquitous. But Word just made it look so easy. And Word brought templates. Documents could be filled in quickly and easily just by completing the right blocks. In no time at all we can have a document that fulfils all the requirements on our checklist. And yet the document has no useful content.
Documentation is an art. And like most artistic endeavours it requires one to have some talent. Either that, or one needs to practise for a long time to learn the right technique. The authors of technical documentation have an added problem: they need to know the skill level of the person they are writing for. Pitch it too high, and it adds to the confusion. Dumb it down, and important information will be lost. It can be a tricky balance to maintain.
So it takes a fair amount of skill and a lot of work to create useful documentation.
Unfortunately, the problems don’t end there.
For the document to be useful, the people who need it must be able to find it. Now librarianship is a degree all by itself. Fortunately, these days, search engines make the job simpler, but there are few business search engines that can rival Google. Even with a good search engine, the information must be published and someone needs to track down all the sources, versions and formats that will need to be indexed. Not a small task at all.
And once people can find your documents, you have a new problem: a document might have once been the authoritative source on all you wanted to know about everything when it was written. But the world moves on and today it could be mostly irrelevant, with parts that are dangerously misleading. After investing all that energy in creating a document, and being able to find it, you need to continue putting in even more effort to ensure that the information stays up to date.
But wait, there’s more. You still need to define the documents — their purpose and audience. There will be the arguments about fonts and formatting. Don’t forget to iron out how you will collaborate and distribute the documentation. And it is probably a good idea to implement some form of version management. Oh, with all those lawyers looking for work these days you will probably want to understand issues of confidentiality, copyright and liability involved in any documentation you produce.
Seems like a lot of work for something so simple. It’s small wonder then that when people start talking about documentation, I try to find a safe spot under the meeting room table. And I will only come out when they have a subeditor, a librarian and a graphic artist to hand — or when they leave the room, which is what usually happens since people who glibly assume documentation is easy obviously haven’t considered what it involves.
There is another alternative: don’t document. Often just talking to someone is a far better way to communicate. Alternately, you can use e-mail to keep a record of the discussion.
Sometimes a far more productive use of time is putting a little effort into making what you are meant to be documenting so simple and intuitive that documentation is no longer necessary.
Documentation still has its place, and there are many occasions where I have wished for something clear and concise that would answer my questions. Unfortunately, experience has shown that such documentation is a rare treasure indeed. So, instead of creating more of these gems, why do we waste days creating volumes that will only serve as padding for the bottom of our desk drawers?
- French is an independent consultant with more than 20 years of experience in the IT industry
Subscribe to our free daily newsletter