DEV Community ๐Ÿ‘ฉโ€๐Ÿ’ป๐Ÿ‘จโ€๐Ÿ’ป

Cover image for Word bugs in software documentation and how to fix them
Victoria Drake
Victoria Drake

Posted on • Originally published at victoria.dev on

Word bugs in software documentation and how to fix them

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. You can find the style guide here.

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.


Use Correct Words

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.


Go forth and write docs

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โ€ฆ

Change my mind meme

If youโ€™d like to help contribute to the OWASP WSTG, please read the contribution guide. See the full style guide here.

Top comments (9)

Collapse
buinauskas profile image
Evaldas Buinauskas

That's great. I also use a Visual Studio Core plug-in called Code Spell Checker. While not being perfect, it has caught so many minor mistakes.

Collapse
ben profile image
Ben Halpern

This is super helpful

Collapse
victoria profile image
Victoria Drake Author

Thanks Ben!

Collapse
bhupesh profile image
Bhupesh Varshney ๐Ÿ‘พ

Wooh! these suggestions were handy!
Thanks

Collapse
victoria profile image
Victoria Drake Author

You're welcome!

Collapse
pauld profile image
Paul

This is great! Not many have wrote about the importance of wording that may seem trivial. I keep a rule when I write up new policies and procedures, to use kiss (keep it stupid simple). Good tips!! ๐Ÿ‘๐Ÿ’ฏ

Collapse
mte90 profile image
Daniele Scasciafratte

A link to this style guide for the documentation is available?

Collapse
victoria profile image
Victoria Drake Author

Here you go! I'll update the article too.

github.com/OWASP/wstg/blob/master/...

๐ŸŒš Life is too short to browse without dark mode