Avoid "Just" and "Simply" in Documentation

Posted on September 20, 2019 by Jack Kelly
Tags: writing, rants

I am often annoyed by technical documentation that uses words like “just” and “simply” to prefix procedures that users are expected to perform. Such words are almost always waffle, and cutting them is almost always an improvement. When you see “just” or “simply”, you can be almost certain the action that follows is anything but. Instead of fixing the root problem, the documentation unconvincingly tries to paper over it.

“Just” and “simply” also insult the reader’s intelligence: the author is afraid that readers will run screaming if not constantly reassured that It Really Isn’t That Bad. If the instructions are deficient in any way, the reader will blame him or herself instead of the responsible party - the author. Again, there are better fixes: make the procedures acutally simple, and make the documentation actually clear and concise. Strunk and White may have gone out of fashion, but I believe that “omit needless words” is timeless. If you disagree, take it up with Orwell. (“If it is possible to cut a word out, always cut it out.”)

Just use the delete key and simply remove the offending words from documentation you write.

Previous Post
All Posts | RSS | Atom
Next Post
Copyright © 2024 Jack Kelly
Site generated by Hakyll (source)