-
Focused product offerings are more appealing to customers than do-everything offerings.
-
Democratic congressional elections indicate that the progressive mandate is bigger than just Obama.
-
Tracing the rhetorical effects and allusions in Obama’s victory speech.
-
A review of recent books about overparenting.
-
Nate Silver gets his moment in the sun. I’d like to have read more about the methodology.
-
This would be the liberal equivalent of Ronald Reagan removing the solar panels from the White House on his first day in office, only with much greater impact.
-
Because if any election needed an epilogue, it was this one.
-
A review of some of the tactics and strategies used by the Obama campaign to win the race.
Day: November 10, 2008
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?