At this month’s WriteTheDocs London meetup, Jim Fisher of Pusher presented a talk called “Don’t say Simply“. He talked about words, such as “simply”, that can seem innocuous when written in user documentation, but which show a lack of sympathy when read.
He showed how popular “simply” is with developer documentation writers, by showing the number of hits for that word in GitHub: 93 million! If you restrict the search to Markdown files (the file type on GitHub used mostly for documentation) , it’s 3,325,386 hits.
“Easy” and “easily” are also problematic, and overused: There are 4,127,104 Markdown pages on GitHub for “easy”, and 2,797,143 Markdown pages for “easily”.
The problem with “simply” and “easy” is that the related task or concept is unlikely to be always simple or easy when the reader needs to read the documentation.
These words are typically “banned” in the main technical writing style guides, but they could be appropriate in training or marketing material. In general, it’s best Technical Authors avoid them.
Here is a link to Jim’s slides: Don’t say “simply” (Write The Docs London, 2018-01-23).
Leave a Reply