Technical Writing Tips for IT Professionals

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.

General Recommendations

  • Determine your write-up’s objectives and audience.
  • Keep the write-up as short and simple as possible to achieve the objectives.
  • 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 write-up before finalizing it.
  • Seek others’ feedback on your text, style, structure and content.
  • Improving writing skills requires a deliberate effort.
  • Most of the following 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.
  • Look for word phrasing that keeps the sentence as short as possible.
  • Split long sentences into short ones.
  • 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 elements of a list.
  • Know the difference between such as and like and use them accordingly.

Advice for Writing Paragraphs

  • Place the 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 need to place spotlight the paragraph.
  • Delete paragraphs that don’t significantly contribute to the flow or meaning of the text.
  • Sentences in the paragraph should be related to each other support the paragraph’s objective.

Tips for Email Messages

  • Strive to keep messages 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 levels of headings and lists.
  • Include at least one paragraph between two headings for introduction or transition.
  • Use the word processor’s style management features for consistent formatting of headings and other text.
  • Assign consistently-styled captions to figures to guide readers to the conclusions they should achieve after reviewing the chart or figure.
  • Place lengthy technical excerpts such as code fragments into an appendix.
  • Refer to every figure and appendix section from the 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 the write-up.
  • 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 the write-up.
  • Avoid unnecessary capitalization.
  • Crop and size screenshots to ensure readability.

Tips for Text Chats

  • You can skip the period at the end of the message.
  • Use emoticons to add non-verbal clues that might exist in a verbal chat.
  • Avoid emoticons and abbreviations that the recipient might not understand.
  • Keep an eye out for the errors introduced by autocorrect.

Post-Scriptum

Authored by Lenny Zeltser, who’s been writing as an information technology and security consultant, product manager, author and instructor for many years. This cheat sheet, version 1.0, is released under the Creative Commons v3 “Attribution” License.

Updated

About the Author

Lenny Zeltser is a seasoned business and technology leader with extensive information security experience. He builds innovative endpoint defense solutions as VP of Products at Minerva Labs. In a previous role, he was responsible for security product management at NCR Corp. Lenny also trains incident response and digital forensics professionals at SANS Institute. He frequently speaks at industry events, writes articles and has co-authored books. Lenny has earned the prestigious GIAC Security Expert designation, has an MBA from MIT Sloan and a Computer Science degree from the University of Pennsylvania.

Learn more