The Language of Your Story
The most difficult skill to obtain, the ability to write well, is beyond the score of this book, but the author will describe the qualities of good writing as a way of providing tips and suggestions to those who lack that skill.
He does a bit to assuage those for whom writing is a mystery - basically, it's a skill that can be developed over time. Make an effort to do it better, and you will. Shrug it off and accept it as a handicap, and you'll never improve.
Clarity means communicating in a language that is simple for the user to understand. Specifically, it means getting rid of the notion that big words and long, complex sentences constitute good writing. Quite the opposite: the litmus test for good writing is that the reader "gets it", and gets it right, with minimal effort.
One obstacle to clarity is jargon. Technical terms are often preferred because they convey a precise meaning to those that understand what they mean in the first place. Write for a layman, and have your work reviewed by someone with no technical knowledge whatsoever. Also pertaining to jargon, resist the urge to invent new terms.
Another obstacle to clarity is a desire to be unclear, as a means of having control. To be complaisant, others may go along with something they don't understand, trusting in the expertise of those that do. This is true in the short term, but when the project is delivered and doesn't perform as needed, more power is lost than gained.
Acronyms should be avoided, or at the very least explained. They are a handy shorthand to using the full words they are meant to substitute for, but unfathomable to anyone who doesn't know those words, and often, the same acronym can mean several different things ("DD").
Be cautious with pronouns, particularly "it" or "they." When three or four things are mentioned in one sentence, the user may not know which of these is the "it" in the following sentence, or even the same sentence. Nice example: "Manufacturing told shipping that they were responsible for placing items in cartons." Each expects the other to be the "they" and the task does not get done.
Write in short sentences with a clear actor and action. Stick to the simple format of "someone acts on something" and do not try to cram multiple actors, actions, and objects into a single sentence.
Avoid the passive tense. It often fails to identify who is acting ("something is done"), and even when it's tacked on at the end ("something is done by someone") it requires the user to mentally chop up and reassemble the sentence to its original intent.
To avoid wordiness, remove any word from a sentence that does not add to its basic meaning. Much wordiness results from the inclusion of facts that are inessential, inconsequential, or incidental. If a detail seems important to describe a specific instance, communicate it in a different sentence or move it to a footnote.
Requirement statements that are general, vague, or ambiguous yield results that may not completely achieve the intended result.
Keep in mind that the requirements must be "testable" - someone must be able to definitively prove that the solution fills a requirement, and the proof should be objective.
When possible, use quantities to substitute for empty words such as "improve" or "facilitate" or "increase" - make the outcome measurable. Nouns can also be ambiguous: "productivity" and "real-time processing" are not clear measurements.
Do not assume, details are known: a system that will provide "the usual quarterly sales report" assumes that the content of that report is known.
Likewise, do no assume the details are self-evident: a system will provide "access to historical data" does not specify what data, and what period of time.
Jargon is likewise a problem to clarity - to say that "transactions will be accessible through an API" does not provide specific details needed.
Buzzwords and management-speak are also dangerous: if a solution "will achieve full virtualization of the system," what does that even mean?
Precision is also confounded by clutter, when the writer attempts to include too many phrases in a sentence, or too many sentences in a paragraph (EN: the author lacks precision in defining what is "too much" in both instances).