Simply Explained

Description

I recently attended a nice talk on documenting open source projects.

One of the top tips was to never use the word "simply". While us developers like to use "simply" to imply it "logically follows that"; if no the off chance the "simple" functionality being provided does not function we are left with the situation that - the user is not helped; and they feel stupid (and thus won't ask for help).

We used the word "simply" 52 times in our docs (mostly in the developers guide and a bit in the OSGi instructions).

Environment

None

Assignee

Unassigned

Reporter

codehaus

Triage

None

Components

Fix versions

Affects versions

Priority

Lowest
Configure