Clarity and conciseness are the cornerstones of technical writing. Our documentation must be easily understood by users, regardless of their technical expertise. To achieve this, we focus on the following practices:
- Use Simple Language
Avoid jargon, buzzwords, and complex sentence structures. Opt for straightforward, plain language that conveys information directly. For example, instead of saying, “Utilise this functionality to expedite the process,” say, “Use this feature to speed up the process.” - Be Specific and Precise
Avoid ambiguity by being specific. Replace vague terms with precise descriptions. Instead of saying, “Click the button,” specify, “Click the ‘Submit’ button in the top right corner of the screen.” - Eliminate Redundancy
Every word in your documentation should serve a purpose. Remove unnecessary words, phrases, or sentences that do not add value. For example, instead of writing, “In order to complete the process, you must first,” simply write, “To complete the process, first.” - Short Sentences and Paragraphs
Keep sentences and paragraphs short to enhance readability. Aim for sentences that are no longer than 20 words and paragraphs that contain no more than 3-4 sentences. This approach helps break down complex information into digestible chunks. - Active Voice
Use the active voice to make your writing more direct and engaging whenever possible. Active voice makes it clear who is responsible for an action. For example, instead of “The report was generated by the system,” write “The system generated the report.”