Redundancy in User Documentation

End user documentation in software industry, to me, sometimes looks redundant. I have had the opportunity to work in few of the software companies which develop software application. As a part of the end user documentation, following documents are prepared to ship with the application:

• Release Notes

• Installation

• User Guide

• Web-Help

• Admin Guide

• Tutorials

The release notes specify different features and version of the software in the particular release, whereas the installation guide describes about the system requirements and stepwise installation procedures of the Software. Sometimes, it discusses about the architecture of the software too, for the better understanding of its compatibility with hardware and other software for operational efficiency. These are the useful information contained in these documents.

Admin guide is another document which takes you through the functionality and features that helps in administering the software. Sometimes, you, as an end user can act as an admin too. In another cases, like in enterprises solution software, there are different individuals who would be responsible for acting as admin.

WebHelp is another documents prepared as one of the applications, to be integrated with the software which comes handy to understand the functionality of the software. The content created with this application contains various web pages linked with hyperlinks with each other and can be navigated through a table of contents. In this, the contents are created keeping in mind the task based approach. Even the particular windows of the software can be linked with particular web pages which are called context sensitive. This entire application is integrated with Help menu of the top menu bar of the home page of the software.

Ideally, the user guides are created to take a walk-through of the software with the minute details. The approach is to focus on every bits and pieces of information about the structure and functionality of the software. However, some of the information contained herein are already discussed in the WebHelp. The tutorial again has the mixed contents of WebHelp and user guide.

Therefore, user guide, WebHelp and tutorials contain approximately 50-60% of similar contents. Some of the software application has exactly the same content in user guide as well as in WebHelp. Only the format of display is different. In industry, it is called single sourcing. The idea is to write once and display in different formats.

Can we call it as effective documentation? In my opinion, certainly not! Because end user find almost redundant contents in these document. The time is come to realize this and give the user the documents which is useful for them. Otherwise, tradition will continue as it is said that a user never reads or consult the documents shipped to them along with the software.

Truly, if user does not find the answers he is looking into the document then definitely he would never consult them. This throws open a question on our credibility of being a technical writer asking whether we are doing our job keeping user in mind or not. This also shows that we are writing a document which is not useful for the users. Well, are we only fulfilling a regulatory requirement or ready to help users?

Remember, being a technical writer we are also a user of the documents that we refer in day today life while working with different software applications. Incidentally, how do you feel when some of your questions does not fetch you answer from the integrated help or user guide on that product? You feel even disappointed when the topic is there but if it is not well explain to guide you to complete a task. You definitely blame the technical writers for sloppy job done. This is a great feedback for you to be self motivated to treat your user valuable and think of the documents which will help them. But not load them with unnecessary documents, which will make them dump these without even looking at them.

So, be creative and use your wisdom.

Collaborative Writing and Reviewing

I follow Tom Johnson’s blog “I would rather be writing”. Tom points out quite correctly that one of the emerging trends in technical writing is collaborative writing and reviewing. It seems logically correct that when the turn around time for any software development is short, there are various writers who work on the same projects or rather write the same manual in parts. There may be several agile methodologies followed for the same project and one individual writer would be associated with one or more team to write about the features their team develops in due course of time. The writer’s job is to write the procedures and instructions involved with the features and finally that gets integrated in the final drafts when the software is getting released. But much before that the written contents pass through the technical reviews and the peer reviews.

One of the major factors I have observed is the process of reviews and the mindsets of the reviewers which differ from person to person. Believe it or not, in our settings the personal competence of the individual writer and reviewer differs immensely. The years of experience spent in the company does make you a senior writer or reviewer but that does not guarantee you to be the real senior in terms of your writing capability or reviewing acumen.

The similar temperaments are quite common among the developers and the testers who instead of validating the technical stuff encroach in the languages sphere, which at time becomes quite annoying. They would come forward bravely and suggest the sentences to be written the way they want. They feel that the way they understand even the common user would be able to comprehend. However, the interpretation of their own ability of the language comprehension is misbelieved and based on the misconception they carry in their mind. Their misconception is also supported by their own misguided belief that they understand the software or hardware to be developed much better than any technical writers. Undoubtedly the understanding of the technical nuances would be any day far more superior to any of the technical writers. Over and above they are the one on whom we depend to get the knowledge to write for the users to be educated.

This superior understanding of them does lead to form a basis of misconception which in reality is not helping the documentation. There are instances when the developers competence in language are far more superior than most of the technical writers. They are welcome to have their suggestions but should avoid verifying that their suggestions are implemented by the writers or not. After all it’s the writers’ choice, wish, and above all, the guiding principles of technical writing and style guide which a writer has to adhere to write the technical documentation. The role of developer should be to support the technical writers with technical knowledge transfer and not impose their own knowledge of language. Let the technical writers be their own masters.

Another flip side of the review is the peer review of the document by any of the colleagues or the team leads. Most of the time, the peer reviews are meant to reveal the missing elements in the documents and the suggestion would just say this is right or wrong, no explanation why its right or wrong. The underlying thoughts are to look down upon the fellow writers and not help the documents get value added. Then I really sometimes wonder why we say that technical writing is a team effort. The given instances do not really show any glimpse of team efforts rather it shows the individual perception of self proclamation of greater self. Does this really help the cause of documentation? Does this really serve the purpose of user? A badly written document would really reflect the bad image of the writer as well as the team for which the writer works. So, where is the so called team factor which keeps on going round in the circle? Truly when we say collaborative writing, its absolutely the team effort.

Therefore, to get the collaborative writing successful, a writer and reviewer will have to look beyond the individual goals and think for the common perspective of user interest. If the goal is not achieved then the document would look as if written by several writers as their own novel and compiled together. But the real meaning of collaborative writing is to achieve greater work in limited time period and the role of reviewer is to get the document be synchronize such a way that it should look that perhaps an individual writer has worked on it. It works really well but you got to believe in it and look beyond your self made selfishness tag to work towards bigger goal.