A collection of mistakes that make documentation less awesome than it could be.
I’ve been an editor longer than I’ve been a developer, so this topic for me is a real root issue. 🥁 When I see a great project with poorly-written docs, it hits close to /home. Okay, okay, I’m done.
I help the Open Web Application Security Project (OWASP) with their Web Security Testing Guide (WSTG). I was recently tasked with writing a style guide and article template that show how to write technical instruction for testing software applications.
I thought parts of the guide would benefit more people than just OWASP’s contributors, so I’m sharing some here.
Many of the projects I participate in are open source. This is a wonderful way for people to share solutions and to build on each others’ ideas. Unfortunately, it’s also a great way for misused and non-existent words to catch on. Here’s an excerpt of the guide with some mistakes I’ve noticed and how you can fix them in your technical documents.
The following are frequently misused words and how to correct them.
and/or
While sometimes used in legal documents, and/or leads to ambiguity and confusion in technical writing. Instead, use or, which in the English language includes and. For example:
Bad: “The code will output an error number and/or description.”
Good: “The code will output an error number or description.”
The latter sentence does not exclude the possibility of having both an error number and description.
If you need to specify all possible outcomes, use a list:
“The code will output an error number, or a description, or both.”
frontend, backend
While it’s true that the English language evolves over time, these are not yet words.
When referring to nouns, use front end and back end. For example:
Security is equally important on the front end as it is on the back end.
As a descriptive adverb, use the hyphenated front-end and back-end.
Both front-end developers and back-end developers are responsible for application security.
whitebox, blackbox, greybox
These are not words.
As nouns, use white box, black box, and grey box. These nouns rarely appear in connection with cybersecurity.
My cat enjoys jumping into that grey box.
As adverbs, use the hyphenated white-box, black-box, and grey-box. Do not use capitalization unless the words are in a title.
While white-box testing involves knowledge of source code, black-box testing does not. A grey-box test is somewhere in-between.
ie, eg
These are letters.
The abbreviation i.e. refers to the Latin id est, which means “in other words.” The abbreviation e.g. is for exempli gratia, translating to “for example.” To use these in a sentence:
Write using proper English, i.e. correct spelling and grammar. Use common words over uncommon ones, e.g. “learn” instead of “glean.”
etc
These are also letters.
The Latin phrase et cetera translates to “and the rest.” It is abbreviated etc. and typically placed at the end of a list that seems redundant to complete:
WSTG authors like rainbow colors, such as red, yellow, green, etc.
In technical writing, the use of etc. is problematic. It assumes the reader knows what you’re talking about, and they may not. Violet is one of the colors of the rainbow, but the example above does not explicitly tell you if violet is a color that WSTG authors like.
It is better to be explicit and thorough than to make assumptions of the reader. Only use etc. to avoid completing a list that was given in full earlier in the document.
… (ellipsis)
The ellipsis punctuation mark can indicate that words have been left out of a quote:
Linus Torvalds once said, “Once you realize that documentation should be laughed at… THEN, and only then, have you reached the level where you can safely read it and try to use it to actually implement a driver.”
As long as the omission does not change the meaning of the quote, this is acceptable usage of ellipsis in the WSTG.
All other uses of ellipsis, such as to indicate an unfinished thought, are not.
ex
While this is a word, it is likely not the word you are looking for. The word ex has particular meaning in the fields of finance and commerce, and may refer to a person if you are discussing your past relationships. None of these topics should appear in the WSTG.
The abbreviation ex. may be used to mean “example” by lazy writers. Please don’t be lazy, and write example instead.
If these reminders are helpful, please share them freely and use them when writing your own READMEs and documentation! If there’s some I’ve missed, I’d love to know.
And if you’re here for the comments…
There are none on my blog. You can still @ me.
If you’d like to help contribute to the OWASP WSTG, please read the contribution guide. See the full style guide here.