Before coming to the United States in fall 2016, I had briefly worked as a technical writer. One of my responsibilities included creating technical guides of a software product.
Having already worked with an entertainment magazine for about six months and having dabbled with creative writing, my language was either too witty or too dense. As a Technical Writer, I had to find a middle path.
I had a tendency to use long sentences which was a big “no-no” in the world of technical documentation. I had a hard time picking up the right language. Then, gradually I learned that people go through user manuals and technical guides not to enjoy the artistry of the prose, but to get right instructions so that they can handle the product well.
I learned simple, straight-forward sentences are the most effective means for serving that purpose.
Writing is so complex that it comes in different forms in different settings. In poetry and fiction, writers can use symbols and metaphors to convey their ideas in a more effective manner. The use of symbols and metaphors in a technical document doesn’t sound like a great idea to me. Similarly, humor and sarcasm are highly encouraged in an entertainment magazine, but it may be confusing and misleading to users if the same sort of wittiness is maintained in a technical guide.
Still, I think the basic idea of all forms of good writing is to find out who your audience is and determine how the message of your writing could be conveyed to that audience in the most effective manner. The style of the prose is determined by the audience and the purpose of writing.
There are many style guides available around. It is a good idea to occasionally look at those guides. They teach us more about “how to avoid bad writing” than “how to do good writing”. I feel “avoiding bad writing” isn’t always enough for a technical writer.
Despite the limitations of the style guides, my favorite style guide is Strunk and White’s The Elements of Style. I enjoy going through this book, and it has helped me a lot in all forms of writings, not just the technical documentation.
One learns the craft of writing through practice. Technical documentation is not an exception to this inevitable truth and all style guides and writing pursuits are useless if you don’t actually sit down and write.
Knowing your audience is the most important part of your writing. A good technical documentation expert is someone who knows the audience well and can translate the technical jargon into a more user-friendly prose.