Tag: productdesign

Screenshots in software user documentation

I’ve been up to my eyeballs in user doc recently, our software-as-a-service product offering having matured to the point that novice users need some guidance to get started with the software. This being a startup, we don’t have a tech writer, and I’ve added the relevant hat to my normal product management job–and rediscovering my deep respect for the profession.

A tech writer has to know the software better than anyone else from the user’s perspective, and has to understand the compromises, incomplete implementations, and other hazards of software well enough to explain to the user how it’s supposed to work in a clear, intuitive way. Tech writing reminds me of Henry Miller’s description of proof-readers in Tropic of Capricorn, which I took many years ago as a motto while working on the production of the second or third issue of Rag & Bone:

The world can blow up — I’ll be here just the same to put in a comma or a semi-colon. I may even touch a little overtime, for with an event like that there’s bound to be a final extra. When the world blows up and the final edition has gone to press the proof-readers will quietly gather up all commas, semi-colons, hyphens, asterisks, brackets, parentheses, periods, exclamation marks, etc., and put them in a little box over the editorial chair. Comme ça tout est réglé…

…A good proof-reader has no ambitions, no pride, no spleen. A good proof-reader is a little like God Almighty, he’s in the world but not of it.

So tech writers are a little like proof-readers–the release may blow up, but the tech writer will still be there updating the user documentation and taking the latest screenshots.

Which brings me around to the question at hand: the tension between the need for screenshots in documentation and the definitive non-agileness of it all. A thread on the Joel on Software Discussion Group questions the need for screenshots entirely but comes around to the concept that, yes, you have to retake the screenshots every time you update the GUI, and yes, it’s a pain in the butt, but it’s part of the cost of doing business. I was hoping for some more practical guidance: is there a rule of thumb on what to illustrate with a screenshot and what to leave out?

A report on the usability testing for WordPress 2.7

Jane Wells at WordPress opens the kimono further on the decision to redesign the administrative user interface for 2.7. I griped a while back that it seemed like the design changes were being made in a non-systematic way, but it turns out there were solid usability testing exercises prior to the surveys we’ve all seen about structuring the navigation menu. She also includes a detailed usability report covering the eye tracking studies and the different stages of the process. Sounds like the new administrative screen is genuinely a usability improvement in terms of the metrics that matter (task success and time on task).

I also found it interesting that participants had a strong emotional connection to the 2.5 admin interface even when the formal usability metrics proved that they had trouble using it! Apparently good graphic design (my attraction to the UI) helps to mitigate formal usability flaws–a point worth remembering.