I am neither the first one, nor an exceptional writer to talk about writing rules. In fact, there are plenty of better writers than me who have elucidated this perfectly. This post is inspired after receiving a lot of feedback from my editor. These are MY golden rules for writing effectively and I intend to print them and paste them on my cubicle wall.
Writing effectively means writing in a manner that the reader does not struggle understanding what you have written. As technical writers, we write a lot of things such as e-mails, user documents, API documents, and so on. After a lot of hard work (or hard words from the editor) I have designed these 5 rules that I use, or must use to write effectively.
1] Expand abbreviations
Though this might seem as a simple thing, it is important to understand why I consider this as Rule 1. We writers spend a lot of time with our product and documentation. We constantly interact with team members and start using their jargon. We are so akin with the product, team, and its terminologies that we no longer think it is important to follow the basic rule of technical writing – Expand abbreviations when you use them in the document for the first time.
We document in a wiki, for us, this rule means doing this on every single page. It is tiresome. But when you put this against a simple logic that a reader might land on any page in a wiki, and that becomes Page One! So, expanding abbreviations is important.
It is not just about abbreviations. When you internalize this rule, you will realize that this is required to avoid ambiguity in the documentation. Instead of just looking at abbreviations, our text should strive to avoid any kind of ambiguity that may confuse and mislead the reader.
2] Make screen elements bold and uncertain elements italics
Or, to cut a long story short – Apply correct font treatments.
Now, this is an area of concern. Before joining the company, I use to refer to Microsoft Manual of Style for Technical Publications (MSTP) – the universal style guide. According to MSTP, we should make all screen elements (GUI elements) bold. Unfortunately, my company does not follow MSTP, which means, I need to unlearn a few things and learn new rules afresh.
What I really mean to say here is, follow the style guide. Dot the i’s and cross the t’s. Trust me, it is not as easy as it seems and I still fumble with a lot of formatting guidelines. The only benefit is that I have a meticulous editor who keeps me in check (sometimes I actually feel she will mark my docs with a red penJ).
3] Match the GUI
Now this is a Universal Truth. There is no room for argument. Whatever is on the Graphical User Interface (GUI; my editor will be so happy!) must be shown as-is in the document. If you have incorrect spellings, bad grammar, wrong usage, the only place to correct it is the product itself. Do not be a saint and clean everything in documentation. You will only end up confusing readers.
Remember the time you couldn’t find that particular check box on the screen when you consulted a help document to upload pictures on Facebook? (OK, I know I exaggerate while citing examples! Don’t your eyes, please)
Did I mention this is a MUST-TO-DO rule? Doesn’t matter if it comes at a third position, this rule is seriously meant to be considered.
4] Write in an active voice, use short, simple sentences
Tell me you all do this already, please. Strange how simple, and silly such rules seem when we are citing them. However, it is not so easy to be simple.
Write short sentences. Do not eat words. Stop using adverbs unnecessarily. Write well.
Inculcate the habit of minimalistic writing. You will go a long way, not to mention, your readers will thank you. Really, I am not lying.
5] Make judicious use of words
I had to use the Thesaurus to see what exactly does “Judicious” mean?
Small things matter. Word choices can sometimes be one of the crucial choices you have to make.
When in doubt always consult the experts and write well.
These are my golden rules for writing effectively.
What are yours?