Communication using only words – whether verbal or written – leaves much to the imagination. Which is part of the appeal when it comes to reading for pleasure. Unlike a great book, most of us don’t read business documents such as a requirements specification for enjoyment. And unlike the book, there can be significant repercussions when one reader’s interpretation of the content varies widely from another’s. So, how can we improve the precision and clarity of documentation without getting too long?
To write or even speak English is not a science but an art. There are no reliable words. Whoever writes English is involved in a struggle that never lets up even for a sentence. He is struggling against vagueness, against obscurity, against the lure of the decorative adjective, against the encroachment of Latin and Greek, and, above all, against the worn-out phrases and dead metaphors with which the language is cluttered up.”
— George Orwell
“If we perceive our role aright, we then see more clearly the proper criterion for success: a toolmaker succeeds as, and only as, the users of his tools succeed with his aid. However shining the blade, however jeweled the hilt, however perfect the heft, a sword is tested only by cutting.”
– Fred Brooks
This is a particularly interesting quote when we consider our deliverables as analysts as tools to be used by designers, developers and QA analysts. The measure for our success is, in truth, inseparable from the success of those that use our work to accomplish theirs.
Sure, there are lots of benchmarks and checklists for the forms and aesthetics of good requirements documentation, but what is the benefit of meeting those criteria if we don’t put our delivery team members in a position to succeed?
With that in mind, how successful a toolmaker are you? In what ways could you improve so as to help those who will use what you produce be more successful?
Here are just a few impressions I’ve jotted down over the past few weeks that may never evolve into full blog posts, but that I wanted to share just the same. Please feel free to chime in with your support or challenges to my list, or with your own observances.