March 23, 2009

The Rubber Duckie Test

Okay, this sounds kind of odd, but hear me out. A developer friend recently told me about the "rubber duckie" method of coding. In a nutshell, you as a software engineer place a generic rubber duckie on your desk. Every time you make a big coding decision or implementation, you explain how it all works to the rubber duckie. If you find yourself straining for an explanation, or if you find yourself unable to even come up with something logical, stop. The duckie has served its purpose -- it's helped you expose a bug or design flaw or implementation flaw that otherwise might have gone unnoticed (until later when the build breaks and it's your fault, or a customer's app crashes and you lose a $2k sale).

This is why technical writers are valuable. We are living, breathing rubber duckies, forcing you to explain your code and decisions (so that we can explain them to users) and thereby helping you uncover errors, inconsistencies, or inefficiencies in your design. And also, because we're human beings, it doesn't look like you're trying to hold a conversation with a squeaky toy.

Things You Wish We Said in Our Docs

An example of some great, actionable user feedback:
3. From the docs: "When you are ready to upload the code, select the correct serial port and NG board type on the Tools menu". This made me want to tear out my own eyes. What are the correct settings!!?

We (LabVIEW technical writers, product support engineers, applications engineers, and yes even developers) try to monitor our forums, we really do. Especially for LabVIEW Base/Full/Pro and especially during beta periods. But it's not always possible, and some things get lost in the shuffle. So we (the technical writers, now) do try to solicit your feedback directly from the help via the feedback link ("Submit feedback on this topic") at the bottom of nearly every help page. Since we introduced this link several years ago, we've received a ton of great feedback, most of which we can do something about :-)

The forums and the increase in user participation always bring up the issue of wikis and user-generated (or at least editable) docs. I'm a little swamped right now so I don't have time to discuss these issues, but rest assured I'll give them the full treatment at a later date, because that sort of stuff is really interesting to me.

But for now: what sorts of tips/tricks/tidbits/information do you wish were in the LabVIEW docs?

Hat tip to Janet Swisher for the link in the first sentence.