In this post, I want to tell you some writing tips that every technical writer should keep in mind to create user-friendly and effective documentation.
You or I
Many technical writers wander what they should use “you” or “I” in their documentation. Well, it depends on the type of technical documentation and who will be a central role in the document.
Using I’ or ‘we’ means a writer is a central role in a document. It’s usually used in reports, memos, business letters, and some types of academic writing where writers want to establish their opinion.
Writing in the second person means you address your reader directly. It gives a document a friendly, casual tone that helps a reader to focus on the content. It works well for writing instructions, memos and how-to manuals. However, this style isn’t appropriate for other, more formal, types of technical writing.
Gender-neutral language
Here are some rules that you should follow if you want to create user-friendly and gender-neutral documentation:
- Do not use “he” or “she” as a generic pronoun because you can’t know exactly who reads your documentation.
- Do not use a feminized noun (e.g., manageress) since the normal noun (manager) covers both sexes.
- You can write “he or she” when it is not awkward or overly repetitive to do so but, nowadays, fewer and fewer people use this construction.
- The better way is to use a plural form. For example, use “they” as a singular pronoun unless you are confident that your audience won’t mind. This usage is gaining in popularity and acceptance, but a lot of people may dislike it.
Writing in Positive Form
Technical writing should be clear — short and concise sentences are what make documentation effective. Using positive language is a great way to make sentences short and snappy. It means that you should say what something is — not what something isn’t. So, your doc content will consist of steps that users should do. If you need to describe some information on what they should not do, for example, in instructions, use an info or warning box, so users will pay strong attention to it.
Use Active Voice
Active voice is what gives your writing authority. It speaks directly to readers, leaving them in no doubt who or what carried out the action, so they will easily get the main idea and don’t have to reread the steps. Passive voice lacks clarity and emphasis, although there are some situations when you can use it, for example, where the subject is unknown or less important than the action. However, even on these occasions, I recommend that you find a way to use active voice.
British vs American English
When you are writing or editing for a British company, it’s important to remember that some spelling rules change when you cross the Atlantic. For example, color vs colour, analyze vs analyse, and the like. When you need to know whether a word is British English or American English, use a dictionary.
But what form you should use? It all depends on your audience, that’s why it’s important to know for whom you’re writing for. For example, you can interview your users to get to know them better. In order to conduct user interviews effectively read this article How to Conduct User Interviews.
If you wonder whether your users will understand your documentation properly or not, use readability metrics to improve your content. Here you can find more information: Readability Metrics and Technical
Technical Writing is Easy