"My Dad is 50 years old, weighs 30 lbs and is 40 ft tall...I like him b/c he is silly"

A very competent and respected colleague of mine, in his early 30s, 5’9” and reasonably proportional I might add, has the following written by his 5 year old son posted in his cube:

“My dad is 50 years old, 30lbs and 40 feet tall and I like him because he is silly”

Besides it being funny and making me think what my daughters really think about me, it reminds me of how our products can be perceived and used by other engineers: They way they see it not they way “they are”.

If you are developing systems, services and products for other developers, it is important to understand that your will be used they way others understand it and not the way you planned it to be used. I have seen a session service used as a general purpose cache, ESB riddled with use-case specific routing logic, authentication service used as data pre-fetch mechanism  and presentation logic (in XSL) saddled with complex and critical business logic – of course in XSL. All examples of how we all use tools to solve our problems regardless of whether or not the tool is meant for it (remember eating jelly with knife?)

The first solution of course is documentation, but here is what that documentation should include:

- Real world, working and end to end examples of the right way to use the services/product

- Examples should be cut-and-paste able (to the extent possible)

- Realistic examples of wrong way of using systems, updated periodically as new misuses surface

- Direction and pointers for how to address the original need leading to the misuse.

- Address of a user (or expert monitored) forum where users can get help