I am a technical communicator who loves words and technology—not necessarily in that order.
I have been a technical writer for 10+ years now. It is by chance that I stumbled upon technical writing as a profession. But once I got into the field, I knew it was my dream job, and since then, there has been no looking back!
Technical writing is more than just writing. Every day you discover something new, and you get to describe it to end-users. If you are naturally curious about technology and are fond of learning, writing, communicating, and teaching, this career might be apt for you.
I have seen people frequently ask in forums whether they should take up a course to understand the nuances of technical writing. Though you can learn a great deal on your own, I recommend looking through style guides and taking an introductory course to learn the fundamentals. It is a form of writing that is different from creative writing, so you need to treat it differently.
If you are an aspiring technical writer looking for a course that can guide you with basic technical writing principles, I recommend the Google Technical Writing Course. It is a free course that is refreshingly easy to understand.
On this page, I have listed some of the key points I picked up from the Google Technical Writing Course.
1. Just Enough Grammar
The first chapter in the Google Technical Writer's Course is dedicated to English grammar. To put it precisely—the chapter emphasizes "Just enough grammar."
You need not have the best command of the English language, but getting the basic grammar right is just about enough. If English is not your first language, this is good news for you.
The chapter demonstrates that English grammar is vast and that no two people can agree on the same thing. However, it is obligatory to correctly use adjectives, verbs, adverbs, conjunctions, transitions, nouns, and pronouns.
Technical documentation does not require decorative words. Google says such words can make the documents unnecessarily complex for users looking for easy-to-understand material. Technical document readers are not on the lookout for wordsmiths. They want useful information in simple language. Unnecessarily confounding them with challenging words that constantly require a dictionary can prove futile. Providing factual information is more crucial.
If you wish to place importance on any English language syntax, let it be the verbs. Using powerful verbs can convert a bland technical document into an engaging educational resource. Google says a verb is the most crucial part of a technical sentence, and we should choose strong verbs to highlight our points.
Terms should be used in a consistent manner throughout the document. For example, if you use "afterschool," stick to "afterschool," instead of going for "after-school," "after school," and so on.
Consistency is key.
If you wish to use acronyms, define them properly for the user first—write the complete form followed by the acronym.
Another mistake I was guilty of—using unclear antecedents, i.e., writing "this" and "that" in my documents without clarifying the reference. Instead of saying "This lets users authenticate," try being more clear about what "this" is. For example: "This combination of keys lets users authenticate." Readers find such sentences easier to understand.
Since we are not in creative writing, we can eliminate filler words. For example, instead of "at this point," use "now." Instead of "determine the location of," use "find." As explained before, technical writing is not about demonstrating your English fluency. It is about explaining the product using the least number of words in the most straightforward and precise way possible.
3. Active and Passive Voice
Did you know readers tend to think in an active voice?
Google (and other style guides) stresses the importance of using active voice instead of passive in our technical documents because it is easier for readers to deconstruct. Passive voice tends to lengthen a sentence unnecessarily. Active voice makes the sentences shorter and more precise.
Google says good sentences in technical writing identify who is doing what to whom. This clarity can only be achieved through using active voice.
If you have been writing in passive voice for a while, it might be challenging to shift to active voice. It takes practice. I am still learning, but I find my sentences easier to understand and more concise whenever they are rewritten in active voice.
Long sentences can be tough to grasp for readers. Break down a long sentence into multiple shorter ones or make a list instead.
Whenever you see the conjunctions "or" "and" in your sentences, it is a good indicator to use an embedded list.
Suppose you follow the previous point and break down a shorter sentence into a list. In such cases, you should keep in mind that all items in a list should follow the same consistency in grammar, capitalization, punctuation, and logical category. List items can be in complete sentences or fragments. It doesn't matter. The key is to stick to one. For example:
This list is:
Notice how all the items follow the same consistency and are parallel. The list is easier to read and establishes a distinct pattern for the readers.
Now, consider this:
- I am writing one complete sentence here.
- Fragmented phrase
- Then I am back to complete sentences again.
The above list is inconsistent and does not follow the same rules. The second item is a fragmented phrase that does not end with a period. Even a combination of active/passive voices can make a list non-parallel.
Apart from lists, tables are also a great way to break the monotony and make your technical material more readable. A few tips on creating helpful tables:
- Before inserting a table in the doc, introduce it with a line of text.
- Name the table columns appropriately.
- Avoid excessive text in tables. Use a maximum of two sentences in each cell.
- Similar to lists, aim for parallelism in tables.
Google says each paragraph should be devoted to one idea alone rather than a concoction of ideas. The opening statement should outline the entire paragraph's motive. This briefing alerts the readers on what to expect and helps them skip the paragraph if need be.
In this day and age, where almost everyone is dealing with a short attention span, short paragraphs can help retain a reader's interest.
Each paragraph should comprise a maximum of five sentences. However, the document should not contain many single-sentence paragraphs, as it can look unprofessional and non-technical.
Last, but definitely not least, is to identify your document's targeted audience. Once the type of audience is clear, you can compose the technical document keeping them in mind.
While writing for your audience, try to avoid idioms, and use unambiguous language as far as possible.
In summary, your technical document should aim to answer the following questions:
- What? – What do you want the reader to know?
- Why? – Why is it essential for the reader to know the information?
- How? – How can the reader use this information?
These points only cover a fraction of what is taught in the Google Technical Writing Course. The training is available for free online, but no certificate will be provided. I would still recommend taking it up irrespective of your experience level. There are many valuable points in the course that can prove helpful to both amateur and professional technical writers.
Take a Moment to Vote!
This content is accurate and true to the best of the author’s knowledge and is not meant to substitute for formal and individualized advice from a qualified professional.
© 2021 Dhanya V