Technical Writing Best Practices

Technical Writing Process

The following technical writing process is important because it ensures clear and effective communication of complex information, improves consistency and accuracy, and helps streamline the overall documentation workflow:

Technical Writing Best Practices

Most technical writing best practices can be inferred from the Microsoft Writing Style Guide and Google's Technical Writing Courses. 

The following is a brief list of key practices and Liaison Education & Knowledge adaptions.  

• Use clear and concise language. Avoid repetition.
• Stay consistent with stylistic choices like lists.
• Avoid use of colloquialisms or slang that could confuse non-native speakers.
• Avoid use of passive voice (e.g., "The bone was picked up by the dog."). Employ active voice whenever applicable (e.g., "The dog picked up the bone."). You can use passive voice if delivering "bad" news (e.g., "This feature is not supported" instead of "Liaison does not support this feature.")
• Generally, write in the simple present tense (e.g., use “A success message appears” rather than “A success message will appear.”). You can also use the simple past ("I ran" instead of "I was running") when appropriate. Sometimes future tense is necessary and/or appropriate; use your own discretion. See Grammarly for an explanation of verb tenses.
• Generally, avoid gerund constructions i.e., where “-ing” is added to a verb (e.g., use “Notice the page reflects the date the score was added” rather than “Notice the page is reflecting the date the score was added.”). Sometimes gerund constructions are necessary and/or appropriate; use your own discretion.
  • This guideline can and should be broken for use in audio narration where the gerund construction can create a friendlier, less formal tone.
• Keep topics (for web help) and paragraphs (for printed documentation) as brief and focused as possible. 
  • To make it easier for readers to scan a page, use header names that summarize content underneath it. Create as many headers as needed (e.g., "Creating a Feature," "Editing a Feature," etc.).
  • Cross-reference (i.e., link) to related or complementary information.
  • Chunk content so only one topic is covered per paragraph or section.
• Use step/action tables to set apart procedures or other types of numbered steps from other information.  
• When creating links, use descriptive language for the link (e.g., “Visit the Applicant Help Center for more information” rather than “Click here for more information”). This adheres to 508 compliance. Refer to this site for more guidance: https://webaim.org/techniques/hypertext/link_text.
• Be sure to be logged in to the E&K team's Grammarly account for technical writing best practices and other standards. Download this document for a summary of the E&K-specific Grammarly style guide.

Writing Emails

• The longer the email, the less likely that it will be read in its entirety. Keep the message to the point and avoid repetition.  
• If there are multiple actions that an applicant needs to perform upon receiving the email, structure them in a list format so it is clear what needs to be done, (and) in what order. List formats are an effective way to organize content and signal to someone skimming an email that there is something they need to do.  
• When possible, indicate any action items in the email subject. Avoid vague subjects like “An important message from [CAS]” or “Information about your account.” 
• Use language and sentence structure that is easier for non-native English speakers or applicants who use a translation service - avoid the gerund construction and the passive voice. Keep the tone professional and friendly, but avoid jargon and slang.  
• When struggling with writing a particular sentence (or editing a particularly lengthy/clunky one), see how many non-essential words you can remove. This helps serve the goal of making emails shorter and more easily translated/understood.  
• Use bolding, italics, etc. very sparingly. It’s tempting to use these to highlight important points, but when overused, it loses its effectiveness. 
• Use a maximum of three external links per email template; otherwise, the email templates become link-heavy.

Content Strategy Goals

"Content" includes both the in-product content (UX/UI design, etc.) as well as supporting help documentation that lives within products and in external help centers.