Article development led by
I have joined a small security startup
and have been tasked with writing up
our internal security processes. The
problem is that I am not a writer—I
am a software engineer—and whenever I start trying to write about our processes, I either stare at a blank screen
until I get frustrated and look away to
do something else, or I just wind up
writing a lot of sentences that later
don’t seem to make a lot of sense.
I am sure there must be a template
that I can work from to get all these
things in my head written down in a
useful way, but I’m not sure where to
look. For example, I want a way to describe to people what they should and
shouldn’t do with our software and
how it must be used so that it provides
the security properties they expect.
What I see when I try to write about
this is a tangled web of spaghetti text.
Normally I would reply that the only
way to get a good spate of writing
done is to go on a three-day bender,
and then before sobering up, sit at
the keyboard and pour your heart and
soul into your text buffer, save your
work, and go on another bender before reading what you wrote. It may
not work, but the benders ought to be
a lot of fun.
In fact, what I am going to do is recommend to you a more than 20-year-
old document, RFC 2119. KV has mentioned RFC (Requests for Comments)
before; this is the set of documents going back to the early 1970s in which the
Internet protocols and many others are
described. For those who are unfamiliar
with these documents, they always specify which parts of a protocol are required
or optional using a small number of key
words: “The key words ‘MUST,’ ‘MUST
NOT,’ ‘REQUIRED,’ ‘SHALL,’ ‘SHALL
NOT,’ ‘SHOULD,’ ‘SHOULD NOT,’ ‘
RECOMMENDED,’ ‘MAY,’ and ‘OPTIONAL’”
(See “Key words for use in RFCs to Indicate Requirement Levels”; https://tools.
The meanings of these words are
codified in two pages in ASCII, a now-ancient standard for textual communication. These key words are CAPITALIZED as their only form of emphasis.
It turns out it is not necessary to have
fancy formatting in order to commu-
nicate clearly; in fact, fancy formatting
often distracts from the message you
are trying to get across.
No, I am not merely suggesting you
use language like this; I believe you
MUST use these terms as written and
then cite the RFC. Getting a group of
people to understand your meaning
by citing, and perhaps beating them
with a well-known and well-written
document, can save you a lot of time
and trouble. The longer a document
is, the more there is to argue over and
the more nits there are to pick. Reducing nitpicking saves a lot of time.
A word of caution when using these
terms in a security document as you
plan to do: The words must be used
carefully and for greatest effect. A long
MUST and MUST NOT
On writing documentation.