Uncovering Documentation

[codenaught]

Original Post: http://geekyjack.blogspot.com/2009/06/uncovering-documentation.html

Do you recall the last time you opened the instruction manual to something, anything, using it for its one and only purpose: assisting you through a process? Maybe it depends on what type of person you are. I for one, am somebody who prefers to master the art of trial and error, making guesses, sometimes completely random and desperate to try to get something to work. But sometimes guessing can only get a person so far, sometimes one must resort to an instruction manual in order to properly troubleshoot or assemble an item that he or she has purchased. Sometimes instruction manuals feel natural and sufficient; think Legos. While other times you feel like an idiot, shuffling through the pages to find out why your product is not turning on, doubting to find your answer, but doing it out of sheer desperation.

I am going to admit that documentation, as I like to call it; the process of writing and rendering documents for instruction manuals, is a hit or miss with people. Some live by it, choosing to lead their life by following examples word for word, while others prefer to dodge reading documentation at all costs. Being one who lives with the philosophy of trial and error myself, it may seem like an unnatural fit for me to be directly involved with documentation on a daily basis. But I am. In 2005 I found myself involved with writing documentation in a official team membership capacity for the Simple Machines Forum software, SMF for short. As sudden as it seemed for me to be involved with the documentation process, things didn't slow down from there. Just under a year after joining the team behind Simple Machines, I was promoted to become the coordinator behind the entire documentation for the software when the previous coordinator was promoted to project management.

What I am going to describe here is just some of the nature of what it is like to "craft" documentation, as I will call it, a form of art so to speak. The entire process behind documentation if done properly can take wit, ingenuity and patience to get done right. Indeed the process behind preparing an instruction manual for any type of product may actually require trial and error to achieve even mediocre results. For instance, an idea for improving the documentation for a product may end up in the gutter, ending up as an ineffective way of communicating instructions. Sometimes it takes a test audience to work out what works well in guiding people through a process and what proves to be poor at conveying the required assistance.

The following is an actual statement I released to the documentation team of SMF in November of 2008, letting them know what I believe is crucial for documentation for the SMF project. What I believe is necessary for the documentation for SMF also applies to the documentation for just about anything:

• Documentation is the key to support; support is the key to maintaining a userbase. Documentation thus is the most critical point in holding a solid suppertbase, and by association is the most important thing in maintaining users.

• Users want clear and to the point documentation. They do not have the time to sit through massive technical documents and dig their way through the irrelevant parts to get at what they want; documents thus should be what the users want: clear and to the point. Documents should put emphasis on the most relevant, and separate the advance technical information from the basic crucial information.

• Documentation should hold to a professional standard of expectation. All officially published documentation should hold no grammatical errors and should be structured in an elegant and logical way; documentation should always make sense and never be unclear, documentation should be of excellent quality.

• The writers of documentation should acknowledge the various ranges of user expertise. Documentation should be available in a way that does not alienate and confuse the most primitive and basic computer user but also to not bore an advance user.

• Documentation should hold to a standard in layout and style. Documentation should always be consistent from one place to another.

• Documentation should revolve around user feedback. The best people to tell us what documentation should be provided and how it should be provided is by the users of the software. The Documentation Team should always try to seek user feedback to know where progress can be made.

The most crucial points I constructed about documentation is that documentation should always put the user in mind. An effective delivery of documentation is only effective because the people writing the documentation sought the feedback of actual people using the product that they are documenting. It is very hard to anticipate what users of a product will understand and what ideas they won't be able to grasp.

Another major point brought up above is the quality of the documentation. I have skimmed through instruction manuals with regrettable typos. When the quality of documentation is awful, one may assume that the person hired to write the documentation isn't fluent in the language they are writing with, and were mainly responsible for some other task in assembling the product but to cut costs they also were assigned the task of writing the instruction manual! This shows that for one, the company did not value the importance of putting out documentation, and only did it because it can be an expected norm in the consumer world. But to the reader, poorly written documentation can prove to be unwholesome (pitiful and messy). This would likely result in not effectively allowing the consumer to understand the instructions.

It is also my belief that when writing documentation, the writers should try their best to separate the more advanced material that not everyone needs from the basic fundamentals. Sure it is sometimes only the advanced topics that one may need to look up for a relatively basic product, but to an average person, reading through a clash of both basic and advanced concepts could prove to be overwhelming. Frequently in instruction manuals this objective is achieved by having an advanced concepts chapter somewhere in the book or to clearly box and label material that is only for the "advance user."

The Typical Documentation Process For Me

When starting a brand new document for SMF I need to perform a variety of tasks to make sure I am going about my work properly. First off, I look around to see if similar material was already covered elsewhere. It can prove demoralizing when one writes something only to find out someone else already started to work on the same thing. After I am absolutely certain that the topic I am to write about has not already been partly or completely covered, I communicate with the members of the documentation team so that they are aware of what I am working on. This is useful to prevent duplicate work.

Next, I check for standards. I look around for documents published in the same section as where the document in progress is going to be published, and examine what type of style and formatting they have so that I can closely match the same type of standards to the document I am about to write. A solid consistency in writing documentation is very important. It is not very appealing to find documents that are written completely differently from one page to the other. When reading through an instruction manual, it is ideal to read through it with the feeling that one person could have written it all, even though in reality a group of very diverse people may have worked together on it.

After checking for standards I get to writing, analyzing the SMF software carefully to document whatever aspect I set out to write about. During writing I check for user feedback to see if people have left advice about what type of information I should cover. I also may communicate with the other members of the SMF documentation team asking for advice and feedback on what to write about or how to phrase a certain sentence.

In the end, the entire process of documentation is like a form of writing. Technical writing to be precise. The kind I am experienced with is a form of group peer review in which we all examine "holes," as in what type of topics are missing documentation, and do our best to fill said holes in with information carefully "crafted" with our keyboards, one tap at a time. We rely heavily on the users of our software to assist in telling us what parts of our online instruction manual [1] is hard to understand, and what topics we are missing documentation on.

I greatly enjoy writing documentation and hope to continue a career that can allow me to pay due respect to those who find themselves writing documentation on a daily basis even if I may not pursue a career that directly involves documentation.

References

Here is the Online instruction manual [1] that SMF provides for its users that I work on along with three other people who are on the documentation team of SMF.

Here is a list of the current Documentation Team behind SMF.

Any questions or comments you are welcome to email me at [email protected]. I will be happy to try to answer any questions that I can that pertain to documentation.

[rune-coders]

Nice i read it all