Creating a ‘Brick-Top’ quality doc

You always gonna have problems trying to achieve quality in one setting. Apparently the first thing to do, is to break down your vision of quality into separate requirements and sort them into 5 categories. And when you got your 5 categories sorted and thoroughly examined, you are free to get rid of anything that does not fit in what you call a top quality doc. Because it is no good leaving for you editor to discover any issues after you marked the version “Ready for Review”, is it? Then I hear the best thing to do is to make your SMEs review the doc. You got to starve them for a few days. Than the sight of it will not look as unappealing as when they have to review them daily. You should collect the feedback and perform necessary updates accordingly. You could do that afterwards, but you do not want go sewing through angry users’ comments, do you?

Leaving Brick-Top behind, it is now time to see what these 5 categories of quality requirements are:

  1. Usability. Why do they need the doc? Users want to use it, rather than read it. Determine the needs and only after that choose the guide to follow. Even standard documents should be customized and adjusted for each particular project.
  2. Accuracy. Does the document describe the actual state of the product? It is vital to be as precise as possible because a small mistake in a manual for a tool at a nuclear power station might result in something a bit more complicated than just a puzzled user.
  3. Completeness. Have I documented all the features? Think from the audience point of view and always double check whether the user really wants to know about that little red button in the middle of the emergency generator control panel.
  4. Conciseness: Do I need Charles Dickens here? Logorrhoea is unacceptable in technical communication. Being inebriated with the exuberance of your own verbosity while writing a document might turn the whole thing into a disaster for the target audience.
  5. Expandability. What if? Think about the future of the project and make the modules of the document customizable. Sometimes they just change the UI and it destroys everything. Maintenance is always easier when your deliverables are flexible.

These are just the general measures. Every project is different, so is the impact of these measures. Moreover, technology will reach the next milestone of development faster than you finish reading this post and you will have to adapt. The correlation between the development of technology and the evolution of the society turns our trade into a stormy ocean. The deeper you dive into analysis, the better the quality of your documentation is. You are always welcome to break down each of the above-mentioned measures into even smaller particles. You are the one to decide the level of precision and assign the appropriate quality indicators. I just gave you a hint on how to think. Analyze, evolve and be flexible.