Helpful Hints for Writing (and Editing) Cybersecurity Reports

When it comes to reading (and editing) (and proofreading) technical documents, it's important to remember that the details are key, and can make all the difference. Not all readers of technical documents have technical prowess, and even those who do will likely appreciate content that is straightforward and at a readable level, no matter their depth and breadth of expertise. This leads to a discussion about Plain Language.

What is Plain Language?

Plain Language is language, spoken or written, that can be understood by a listener/reader the first time it's encountered. While its aim is clarity, consistency, and just general accessibility, it is not "dumbing down" content (a phrase I strongly dislike). It's making our points through relatable language that basically says what it means and means what it says. Cue Alice in Wonderland's March Hare…

Plain Language is actually a U.S. federal government law, signed into effect in 2010. The Act states that government documents and information should be clear and effective for public understanding and use. With the sheer range of comprehension and motivation among readers, this Act at least focuses on the access piece. So then, which techniques can help achieve this standard outside of the government sector, and how can we apply these goals to technical writing for cybersecurity?

Templates for the Win

Does your organization use templates for writing technical reports? If yes, it's a good idea to stick to the template, in general, most times. This helps your technical editors to get through the content more seamlessly—any time the brain has to "switch tracks" it can be distracting, leading to longer read times and general questioning about what else may be different in the report.

Also, if templates receive updates, be sure to apply those updates on your end as soon as possible after their issuance. This will help your Quality Assurance (QA) team be more efficient (see points made in the paragraph above). Basically, be sure to break up with that old template and start anew. It helps to get us all on the same page, literally.

Lastly, legal wording changes may be made to the templates. It's imperative to stay updated and in lockstep for this reason alone.

Creating Engaging, Clear Content

Speaking of minutiae, formatting marks can be your best friend in reports. When this function is turned on Microsoft Word, it helps you to see extra spaces, tab alignment, paragraph or page breaks, etc. This can be especially helpful when formatting to eliminate white space (all that extra space in documents that is not needed). Turn on the symbol below in Word, as needed:

As mentioned, it is a good, and helpful, idea to stick to the script with templates. If something does need to be altered or if a custom report request is made by a client (such as using a differing rating scale), you can let your QA team know. A simple note will do the trick and help keep us out of the weeds.

Lastly, business writing is succinct and to the point. There isn’t a lot of fluff or extra, so no need to write things like during the engagement or during the testing several times within a walkthrough. You can also moderate how many times you use words like "Next" and "However" in order to avoid repetition and break up the narrative. A simple search with Control + F on a PC or Command + F on a Mac will allow you to easily find each instance. Note that another, more evident way to search this in Word is by opening up the Reviewing pane from the Review tab, then clicking on the magnifying glass in that pane and typing the word(s) in the Find and Replace field.

Another suggestion is to not start each sentence with the same wording, especially not in a row. 

Example:
BestHackingCompany…
BestHackingCompany…
BestHackingCompany…

Passive voice in writing is OK, so having 'Attempts were made to brute-force the password' are just fine, to help the technical story roll along.

Making it Match and Doing the Math

Technical reports are just that—technical. That means lots of findings titles, rankings, ratings, and tables. Information that is presented at the beginning of the report may appear later on, such as noting a Strategic Recommendation in an overall recommendations table and then spelling out that recommendation in a spot, or spots, further down in the document. Especially for compliance documents, think NIST, ISO, CMMC, you want things to match up for clients on the audit-track.

Specific to findings, in order to provide complete, accurate information to your clients, make sure the number of findings in the Technical Findings section matches the number of findings in tables/charts. Same for the Severity Rating/Attack Complexity, or whatever monikers your organization uses. For example, having ‘High Severity, Advanced Complexity’ in one spot but 'Medium Severity, Expert Complexity in another for a single finding doesn’t jive. The rating details for a finding need to match up throughout the report for each mention.

Same idea for content that repeats itself, like listing three jQuery libraries – 1.12, 1.7.2, and 3.4.1. If you list those in a certain order, say ascending, in one spot in the report, then I suggest putting the screenshots, for example, in the same order as the libraries were presented in the narrative text. Just a little trick to keep things flowing logically in the reader's mind.

To manage these nuances when editing, I perform audits by taking screenshots, saving those screenshots in a notes program, and visually comparing those notes to the report document content. Copying the content and putting it in the Find search also works, but I personally like the side-by-side.

Eagle-Eyeing It

Is all of this super-detailed work? Yes. It is tedious? Yes. Does having content that's accurate and consistent across the document matter? Yes. Namely for two reasons—first, it makes you, your knowledge and assessment work, appear trustworthy, and second, it reduces the reader's burden, which is my main goal as a Technical Editor. 

Ultimately, focusing on small things like capitalization, spacing, and acronyms (letters pronounced as one word, such as NIST - National Institute of Standards and Technology) or initialisms (letters pronounced as individual sounds, such as PCI - Payment Card Industry) really can have a big impact. Also, if a term is capitalized in one spot in the report, it should likely be so in any other usage. Of course, code is an exception to this.

Landing the Wording

Specificity is a key component of solid plain-language writing. Therefore, using pronouns, such as "it" and "they," should be avoided. Use those tech terms instead! Note that trying to avoid pronouns in sentences might sound redundant (accurate, but redundant). Example: TrustedSec initiated a backup of the device and found that backups were required to use backup passwords to make encrypted backups. This sentence gets an A+!

Consistency is Key

Being consistent with how terms are presented within the report makes comprehension easier on the reader. For example, if there is one attacker but the report vacillates between saying attacker and attackers when explaining the issue, the reader's mind has to expend energy to process this difference. Another example is using application and applications in a report. If only one application was tested, then application (not applications) should be used when describing testing specifics.

Business Professional

Our reports are professional documents, so using colloquial language/abbreviations should be avoided. For example, instead of putting HQ, put Headquarters. Other examples are to use employee instead of worker and Operations team instead of Ops. Spelling out usages lends itself to professional-sounding discourse.

Reviewing the Review

Once you receive your copy-edited document back from your reviewer, It’s a good idea to save a copy of that document to your desktop for a minute. You can go back and review the edits before jumping into your next technical or advisory report. I personally save important points, aka things to remember, in a notes app and search through it like I would a Find in a Word document, for both wording and technical things I need to be consistent on.

A Guide with Style

Lastly, be sure to review any Style Guide(s) used at your organization for best practices in grammar, semantics, and formatting. While not infallible, the guide should outline many of the topics needed for consistency amongst writers, departments, and divisions, to help steer everyone into a common "sound" purported by the organization. In essence, look to a Style Guide for answers and use Control + F or Command + F to search for particulars.

In Sum

While cybersecurity has many frameworks and systems to address, it's a good idea to frame one's own mind on some small tweaks for writing up reports related to these and other cyber-focused topics. Doing amazing testing, reconnaissance, interviewing etc. is only enhanced by making sure all that content-goodness is presented articulately, accurately, and timely. 'Putting the bow on' is my job, and the steps I mentioned throughout this post can contribute to that objective.

Writing Wrap-Up

Know that writing in plain language is an iterative process and takes time to master. It can actually be harder to keep things simple than not! Getting the hang of wording, sentence structure, and narrative flow that a reader can understand the first time they read it, whether they’re a subject-matter expert or not, is a challenge.

From someone who is non-technical, reading technical content on the daily at work, if we all just go one edit, or writing adjustment, at a time, we'll get there, wherever that is (maybe I'll ask Yoda…bet he knows).

Bonus Resource

If you're looking for an easy, helpful site to seek out synonyms and more, I suggest using Word Hippo: https://www.wordhippo.com.

And, be sure to circle back to the Plain Language tips from the Act mentioned earlier.