Why would Technics Publications publish a book outside its specialty of data management? We published Graham Witt’s Technical Writing for Quality for two reasons. First, Graham is a world-renowned data modeler and the author of Data Modeling for Quality, and therefore many of his examples are in the field of data management. Second, and more importantly, we all need to know how to write. Whether it is a technical requirements specification, an attribute definition, or an explanation of how certain application features will function, writing with clarity and conciseness is essential.
Technical Writing for Quality will assist anyone who wants to improve their writing. It covers what makes written communication effective and, even more importantly, what makes writing ineffective. It contains practical advice for the technical writer, covering choice of words, arrangement into sentences, document organization, and layout. It contains numerous examples of both well-formed and poorly-formed statements.
Here are Graham’s own words on why he wrote the book. (This subset of the book’s introduction is copied with permission from Technics Publication.)
Having worked in IT for five decades in many roles, I have spent much of that time writing or reviewing not only code, models, and databases but documents. These include tenders, recommendations, business glossaries, requirements specifications, user manuals, and standards documents. When such documents have been understandable and unambiguous, the activities supported by those documents have been effective and efficient, but all too often, where documents are unclear or ambiguous, costly time-consuming rework has been required.
While IT projects involve modeling and coding, both forms of human-machine communication, a major contribution to the success of a project is the quality of human-human communication, both orally and in writing. This book is for anyone who wants to communicate more effectively when writing in the English language. Its primary target audience is IT professionals who need to document what they do for the benefit of others. It may also be of value to professionals in other fields.
Every IT professional needs to communicate with colleagues, clients and other human beings using a common language, even if only in the form of data definitions, process descriptions or business rules. Many need to write formal documents as part of the documentation of a new system or data resource.
The purpose of written communication is to express assertions or questions in a manner that the reader understands. Written communication involves the writer visualizing a set of related mental concepts and translating it into a natural language, which the reader then translates into their own mental picture. Communication is only effective when the reader creates the same concepts and relationships as the writer. If the reader is (a) unable to create any meaningful concepts and relationships, or (b) creates concepts and relationships that differ from those of the writer, communication has broken down.
Writing may be ineffective for several reasons. Ambiguity makes writing less understandable, as do poor document organization, poor sentence structure, unclear argument, verbosity, and inappropriate word usage. A document with any of these failings lacks clarity: it is difficult to understand and therefore poses risks to the organization using it. For example:
- in requirements, lack of clarity may lead to acquisition of a system lacking required features or may lead to money or effort being expended on unnecessary features.
- in system specifications, lack of clarity may lead to rework, increasing the acquisition cost and timeline.
As a student in England and Australia in the 50s and 60s, I was taught grammar, but as a teacher in the late 60s, I discovered that “self-expression” had replaced grammar in the curriculum. I then worked in a variety of organizations in which management, schooled in English usage rules, expected documents to follow those rules.
However, in many of the documents I have reviewed in my IT career, I have repeatedly observed the same issues, in particular:
- overlong sentences, resulting from either too many ideas crammed into the one sentence or the inclusion of superfluous words that added nothing useful
- poorly structured sentences, often resulting from adding at the end of a sentence words that should have been included elsewhere in the sentence
- the use of words like the one the writer most likely had in mind—but unfortunately the wrong word for the occasion
- circuitous arguments, in which the writer has obviously struggled with multiple options and their advantages and disadvantages but has not set these out clearly
- ungrammatical sentences.
Even in this introduction, you can get a feel for Graham’s descriptive, yet precise writing style. This makes the book easy and enjoyable to read while at the same time, chock full of useful writing techniques. For example, I always use a serif font for formatting tables. Graham recommends a sans serif font and explains why in section 2.3.6.
You can learn more here, and you can also attend Graham’s free book release celebration on May 23rd at 4:00 pm Pacific Time. Register here.
