7 Reasons to Start Publically Documenting Your Product

"Do it now" by Nick Youngson

If you sell a product, it’s your job to make sure people can RTFM. Stop joking about product documentation and start doing it right. Any product that needs a manual to work is broken. (Elon Musk) A user interface is like a joke. If you have to explain it, it’s not that good. (Half the […]

No, You Don’t Need An FAQ. FAQs Must Die.

It's not the questions people are looking for

I’ve never been on Jeopardy, although I watched it on occasion when it was still running in Norway. As much as I enjoy trivia games, this was never a favorite of mine. The “answer must be a question” rule leads to lots of contrived questions, and contestants get eliminated for not remembering the “Simon says” […]

Link Roundup: APIs and Fine Manuals

Still wrestling with my next post on error messages. Meanwhile, I’m sharing some excellent links on technical communications I’ve happened upon lately. Ten Reasons Developers Hate Your API (and what to do about it). Some great take-aways for anyone involved with APIs and their documentation here. And yes, terrible documentation is reason number 1 on […]

The Three Most Annoying And Least Helpful Types Of Error Messages

Avoid annoying your users, focus on being helpful

Error messages are a constant source of frustration to users of all skill levels. A recent example is Don Norman’s rant Error Message Are Evil (sic) on LinkedIn, where he insists that error messages must start collaborating with the users, and that software needs to become better at anticipating and accommodating actual user behavior. As […]

Helpful Error Messages For Fun And Profit

Grafitti: Support grows for the war on error

Nobody is keen to invest in error messages. And by invest I mean energy, money, man hours … Declare “Our product will excel at failing gracefully”, and you can probably count on your stakeholders to drop off after “excel at failing”. Everybody fails (sometimes) But every. Product. Fails. Networks happen, unexpected input happens, integrations with […]

Kill Your Darling Tech Analogies (Almost Nothing In Life Is Like A Car)

Old car matching a building in Grünerløkka, Oslo.

Over the years, I have come to fear and loathe most uses of metaphor, simile, and analogy in technology discourse. Interesting, helpful analogies are the exception rather than the norm. What makes a bad analogy? The main problems as I see it, are that the images people use tend to be: Unoriginal and predictable. 9 […]