“Good computer security documentation teaches practical
solutions clearly. Yet, too often security documents suffer from
too little explanation and too technical language. Much
technical documentation in general, and computer security material
in particular, assumes too much on the reader’s part. For an
example, read this opening sentence describing the Unix “find”
command on a “man” (manual) page:
The find utility recursively descends the
directory hierarchy for each path seeking files
that match a Boolean expression written in the
primaries given below.”
“If the intended audience is computer science instructors or
professional programmers, the terminology serves the task well. For
general audiences, however, the diction level is probably too
advanced. The questions that arise include:
- What does “recursively” mean?
- How is the hierarchy structured?
- What is the precise meaning of the word “path”?
- What is a “Boolean expression”?”