This cheat sheet offers guidelines for IT professionals seeking to improve technical writing skills. To print it, use the one-page PDF version; you can also customize the Word version of the document.
Lenny Zeltser, the creator of this cheat sheet, is the author of SEC402: Cybersecurity Writing: Hack the Reader. Click the link to learn more about the course.
General Recommendations
- Determine your writing objectives.
- Understand what your readers want to see in your text and how they want to see it.
- Keep your message or document as short and simple as possible to achieve the goals of both parties.
- Use terminology and tone appropriate for the audience.
- Craft your text with the understanding that some readers will merely skim it.
- Enable spelling and grammar-checking tools.
- Don't plagiarize. Err on the side of caution. When in doubt, attribute anyway.
- Carefully read your text before finalizing it.
- Seek others' feedback on the structure, look, words, and content of your writing.
- Improve your writing skills through deliberate efforts.
- Recognize that these tips are just guidelines. There are always exceptions.
Advice for Writing Sentences
- Delete words whose absence doesn't significantly deter from the meaning of the sentence.
- Keep your sentences short.
- Be consistent regarding the Oxford comma.
- Avoid passive voice, which often leads to ambiguity and confusion.
- When feeling the need to use a semicolon, parenthesis or an em dash, consider breaking the thought into separate sentences.
- Maintain structural and stylistic parallelism across your headings and list elements.
- Know the difference between such as and like and use them accordingly.
Advice for Writing Paragraphs
- Place your most important point in the beginning of the paragraph.
- Split long paragraphs into several short ones for easier reading and skimming.
- Avoid one-sentence paragraphs unless you want to place spotlight on the paragraph.
- Delete paragraphs that don't significantly contribute to the flow or meaning of your text.
- Make sure the sentences in the paragraph support the paragraph's objective.
Tips for Email Messages
- Try to keep your message shorter than 3 paragraphs.
- Lead with the strongest statement to grab attention.
- Assume the recipient will read only the first 2 sentences.
- Use the Subject line to get your main point across.
- Keep the message personally-relevant to the reader.
- Don't respond in the heat of the moment. Take time to reflect.
- Be specific about what action you'd like the reader to take or which conclusion the reader should reach.
- Consider whether email is the best medium for your message.
Tips for Longer Reports
- Use a consistent, generally-accepted style for capitalizing words in a title.
- Pick a title that'll catch the reader's attention while also setting their expectations.
- Create a strong executive summary that stands on its own even if the reader ignores the rest of the report.
- Split the report into multiple sections to logically group and separate contents.
- Strive for a simple structure, avoiding deep nesting of headings and lists.
- Include at least one paragraph between two headings for an introduction or transition.
- Use the word processor's style management features for consistent formatting of headings and other text.
- Craft captions that guide readers to the conclusions you want them to reach about the chart or figure.
- Place lengthy technical excerpts such as large code fragments into an appendix.
- Refer to every figure and appendix section from your main text.
- Make sure the headers and footers include the right notices (copyright, confidential, page number, etc.).
Formatting Guidelines
- Err on the side of simplicity when selecting a visual style for your document or message.
- Use italics or boldface, not both, when emphasizing.
- Know the difference between em dashes and hyphens, and use them accordingly.
- Avoid breaking short lists or paragraphs across pages.
- Insert a single space, not 2, between sentences.
- Keep font size and typeface consistent throughout your report.
- Avoid unnecessary capitalization.
- Crop and size screenshots to ensure readability.
Tips for Text Chats
- Skip the period at the end of your message if you want.
- Use emoticons to add non-verbal clues that might exist in a verbal chat.
- Avoid emoticons and abbreviations that the recipient might not understand.
- Watch out for the errors introduced by autocorrect.