In the IT world, and especially in security, we write a lot of reports. We often get the technical information right but the presentation can be a little dry, which can limit the impact. The following began as suggestions for writing penetration test reports (roughly along the lines of the SANS SEC560 template), but they can apply to other reports as well.
- Remember your audience. Confusing who will read each section risks confusing or talking down to the reader. The Executive Summary provides necessary information to people who may be entirely non-technical. The Summary of Results gives the IT people enough information to understand the mechanism. And the Conclusion sits somewhere in between for those who have some technical knowledge.
- “Don’t use seven words when four will do.” This advice, originally delivered by Rusty to Linus in Ocean’s Eleven, holds true in many things, but especially in reports. It’s easy to lose a reader when your phrasing goes longer than necessary. For example, the phrase “attempted to gain access to” can often be shortened to “attempted to access”. It may seem minor for one phrase, but I can often slice out multiple lines in a paragraph by doing this, making point easier to deliver and sometimes saving entire pages over the course of a report.
- Avoid the use of ‘be’ verbs. These words (am, are, is, was, were, be, being, and been) can render a sentence static, even boring. Avoiding these words can help turn an otherwise dry report into something more interesting. “The tester discovered a flaw” will interest a reader more than “The flaw was discovered by the tester” (and follows the point above). Sometimes this can turn a sentence unwieldy, so watch for that, but it generally works well.
- Trust the grammar checker in your word processor, especially in Microsoft Word. Even as someone who prides himself on excellent grammar, I find myself breaking rules that Word catches. When in doubt, check grammar sites to confirm the correct form.
- Abbreviate long, multi-word terms that will be used more than twice, even if no standard exists for that term. For example, the Foobar Content Management System can burden the paragraph with repetition. By shortening it to FCMS after the first use, it makes the paragraph much easier to read.
- In general, refer to the “tester” or “testers” instead of the Team (or the wordier <Company> Penetration Testing Team). Mentioning the Team in very general places is appropriate, but in the Summary and Conclusion (and to a lesser extent the Executive Summary) when discussing a given accomplishment, referencing them in this slightly more specific way gives more credit to the tester that achieved a goal while limiting interpersonal interactions.
I have other practices, but they mostly tie into the specific word processor that I’m using. These work whether you’re composing the report in Word, LibreOffice Writer, Notepad++, or ed (though the last two may make adding screenshots tricky).