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.