Show Menu

Basic Technical Writing Practices for SMEs Cheat Sheet (DRAFT) by [deleted]

Basic Technical Writing Practices for Subject Matter Experts

This is a draft cheat sheet. It is a work in progress and is not finished yet.


Standard Operating Procedures (SOPs) are written instru­ctions that a worker follows to perform a given task consis­tently and effect­ively. These documents commun­icate who will perform the task, what materials are necessary, where and when when the task must be performed, and how the worker will execute the task. Well-w­ritten SOPs are a corner­stone of quality system docume­nta­tion, and they contribute to the scalab­ility of a company.

It takes skill, training, and practice for indivi­duals to become proficient in technical writing; however, technical docume­ntation managers can add value to the SOP develo­pment process by giving Subject Matter Experts (SMEs) the tools to effect­ively contri­bute.

10 Basic Technical Writing Best Practices

1. Consider the reader as you write. People differ in age, education, knowledge, skills, and experi­ence. Work cultures also differ. Determine the writing style and level of detail that makes the most sense for those performing the process or task. Consider why the reader needs the inform­ation and how they will use it. You can even take notes to remember the points you want to cover.
2. Focus on the writing process, not the output. Create a first draft with your audience in mind. At this point, don't worry about quantity of your output. You can edit your work later to shorten it.
3. Use correct English. Just like engine­ering, written language has rules that should be followed to remove ambiguity. Famili­arize yourself with grammar books and Style Guides as applic­able.
4. Be concise. Keep your sentences short and to the point. If the SOP is longer than 10 steps, consider breaking it up with visuals.
5. Use visuals to support your text. Use flowch­arts, tables, and graphics where approp­riate and necessary for clarif­ica­tion, and make sure that any text included is large enough to read.
6. Be consistent with word choice. Don’t use different words to mean the same thing, especially for technical terms. Add a glossary if needed.
7. Keep it singular. Use the singular rather than the plural when describing relati­onships to minimize confusion.
8. Use parallel structure. Order your text so that the reader can easily see how related concepts are different and how they are similar. (See examples here.)
9. Review your draft. Edit out any inform­ation that your reader does not need to know or that might confuse the reader.
10. Don’t be afraid to outsource technical writing. An engineer adds value to a company by concei­ving, designing, and producing systems and products for a recognized need. If basic technical writing skills don't come easy or are taking up too much of the engineer's valuable time, use a technical writer that specia­lizes in your industry for some or all of the SOP writing process

Technical Writing

6 Tips Create Meaningful Product Docume­ntation

1. Identify your audience before you start writing. And write how they will be using your product docume­nta­tion.
2. Choose a delivery method that best meets the needs of the end user. Present docume­ntation in a way that is easy to use, enhances the user’s product experi­ence, and reduces the need for service calls.
3. Use a visual­ly-­app­ealing format. Well designed, easy-t­o-use learning and reference materials will make your product and company stand out. When designing text, include inform­ative headings to draw the user’s attention to specific topics. Break up the inform­ation into short segments for easy unders­tan­ding. Use graphics and tables to support the text.
4. Write the way you speak, and use personal pronouns.When users feel that you are talking to them, they tend to learn quicker.
5. Keep sentences short and to the point. Cover only one subject in each paragraph. Keep paragraphs under 12 lines with an average sentence length of 20 words.
6. Test your docume­nta­tion. As part of the review and approval process, make sure all product docume­ntation adheres to relevant regula­tions and standards.