When I perform an editorial pass over content written by developers, I often come across the same kinds of technical writing mistakes, over and over again.
- Couching things in the future tense, when the present tense is considered more concise. E.g., “Clicking Print will print the document.” Would be better written as “You can print the document by clicking Print”. This helps ground the reader in the here and now.
- Use of passive voice instead of active voice. When you use active voice, the sentence has a subject that acts upon its verb, which is easier to understand. E.g., “You can instantiate the object”, as opposed to “The object can be instantiated.
- When referring to the developer user, authors use sentence constructs like “The developer can..”. Instead, the you should speak directly to the reader. You do this by speaking in the second person. E.g., “You can…” This forces the reader to imagine themselves performing the action, which provides a better user experience.
- The use of bulleted list items, when numbered list items should be used. Any list of items that should appear in sequence should be numbered.
- Don’t say “please” when you’re giving direction. Save “please” for personal communications.
- In a procedure, performing multiple steps in a single step. Steps should be for completing one task only.