[ Article ]
The Problem with Documentation

Good documentation or technical writing is often believed to lie on a writer’s ability to write well and on his command of the language. It is further believed that if that writer is also a subject matter expert on the subject to be written they are assumed to be able produce a well written document or manual. While there are some merits in those beliefs, it isn't a correct one.

A well written document needs to be understood by the reader and it has to be easily understood as well. Many companies that produced their own documents appoint one of their own staff as the writer. This is where most documentation failed to achieve its purpose. The documents produced are often incorrectly focused. Not enough emphasis is placed on the reader or end user of the document.

Often documents and manuals are written by the document owner or a member of the technical development team. The belief is that no one can better understand the business or system than the owner or the developer themselves. While this is true, it is often filled with many incorrect assumptions such as:

• The use of jargons assumed to be understood by readers.
• Insufficient explanation of practices assumed to be common knowledge or common sense.
• Over explanation of details assumed to be important and what users want when they actually don't.

Business owners know their processes too well and omits details passed off as common or basic knowledge. Technical owners (Systems developers) are too eager to "boast" of their system by detailing too much. You can't fault them, it is afterall their "baby".

Inexperience document writers will place their emphasis on a documentation process. However, a process is only good for collecting information to develop the document; it is by no means the solution to writing a user friendly document. Having a good process for gathering accurate information for the document is crucial but we must not confuse that with what users want or need.

Writing a good manual or document that is user friendly comes from experience and the key factor is understanding users.

A major problem with producing documentation is the dislike for it. Almost all document owners I had spoken to do not like performing documentation work. The main reason sighted is that documentation is boring. To make matters worse, documentation is often not regarded as part of their primary job scope and considered as additional and unwelcomed work.

Companies will continue to face problems with documentation without realizing that writing manuals is a full time commitment. If you don’t plan on outsourcing the task, a staff assigned to produce documents should be relieved of other commitments. It is worth noting that documentation requires a specialized skill that comes from experience and specifically understanding users.
 

About The Author Lo Wai Munn is a trainer, a technical writer and web content professional with more than a 15 years of experience. He has authored several manuals for international distribution and process documents for multinational companies. He was a recipient of a Letter of Commendation from the Ministry of Education, Singapore, for his involvement in training and user manual development.

If you are looking for technical writing services that your readers will appreciate and use, contact us for a non-obligatory discussion today.