Cyber Defense

Writing Tips for IT Professionals

 

writing-tips-for-it-professionals-review-large-1

 

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.

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. Lenny also created a short writing course for cybersecurity professionals.

This cheat sheet, version 1.1, is released under the Creative Commons v3 "Attribution" License.

Post a Comment






Captcha


* Indicates a required field.