The Story of a User Manual

I often hear questions like "What is a user manual" and "How do you write a user manual" from new technical writers. This is what prompted this write-up. In the next few paragraphs, I will describe the steps that go into creating a user manual. At the end of this write-up, I hope to have answered the questions that I started with.

In the beginning, there was the Word.
There'll be reams of paper to wade through. There will be the software specifications, the software requirements, the user requirements, the notes jotted down by the developers, and sometimes, a user manual of a previous version of the product. It does seem a bit mindboggling at first, but that is exactly what Technical Writing is about – spreading the Word.

Then God said, "Let there be light", and there was light.
We, as technical documenters, introduce a product to a user. So, it is essential that we have a clear understanding of the product that we're documenting. How do we go about it? We read the legacy documents, we play around with the product, we study the domain that the product belongs to. Why is the last so important? Well, if we are documenting the GGSN server, for example, it helps to know at least the fundamentals of networking. This is the stage where we get our concepts right, and clear our doubts about the whats and the whys (tackling the hows come later).

And God separated the Light from the Darkness.
Too much of light can be blinding, and things do tend to seem clearer when viewed through filters. So, we parse the information. What we are writing is a user manual. Who is this user? A system administrator? A shopfloor engineer not very familiar with Windows operations? What would such a user use the manual for? Troubleshooting? Operating? Installing? A bit of all three? We analyse the reader requirements, and create a skeleton for our user manual. We arrive at the broad outlines of the information that will go into the manual, and the organisation of such information.

Then God said, "Let the earth put forth vegetation: plants yielding seed and fruit trees of every kind."
Armed with an understanding of the product, and of the user for whom we are writing, we now get down to the actual business of writing. And illustrating, if needed.

God made the two great lights – the greater light to rule the day and the lesser light to rule the night.
Lights help us navigate. The TOC is a broad navigational aid; the indexes and the glossaries are those little extras that render a document that much more user-friendly. A highly technical reader does not need definitions but if our intended users cover a broader spectrum, we need to include a glossary. An index is an absolute essential for any document that has more than one chapter but it does not help much if all the index entries are mirror images of the TOC entries. Why? Because a reader turns to an index (or a search) only after failing to find the information in the TOC.

Then God said, "Let us make humankind in our image."
We now have a document. But we have not tested it yet. Is it in the "likeness" that we intended it to be? We pass on the document for review – usually the development team will do it but if they are too busy tackling last minute enhance-requests, and fixing those murphys-law-bugs, they may not exactly be disposed to read our document and review it. In such a scenario, it is best that one sits with the document in one hand and the product in the other, and see whether the two match. If it is an installation guide – do the steps described in the document yield exactly the same result that the product is now showing me on the screen? Has the GUI changed in the time that I last saw the product? Is the product now called something else? We check all these and correct our misses. Then, we pass it on to a language editor, get the review comments and incorporate them.

And on the seventh day, He rested.
But before resting, we ensure that we've followed all the version control policies. Then, we can take our team out for lunch.

This, in brief, is the genesis of one of the main deliverables created by the technical communicator community.

And then, there's Darwin but that's for another day.