Eating Your Own Dog Food Was: Interviewing Subject Matter Experts

[Berk/Devlin <armadill -at- earthlink -dot- net>]

On Tue, 15 May 2001 15:17:45 -0700, Carma
ccallen -at- beckman -dot- com wrote:
>"Brierley, Sean" wrote (and others agreed):
>>(snip)I had always thought using and learning (quickly) about the item you  were documenting was the best, nay, only way to effectively communicate the
>> subject in a way that is understandable to any target audience.
>
>That probably works best if all you're doing is telling software users how
>to use an application, but there are many, many writing projects where this
>approach is not just impracticle--it's downright impossible. When I was
>writing flight manuals for the USAF, they would have been quite reluctant
>to give me a $25 mil airplane to fool around with and try to figure out how
>to keep it in the sky. They probably wouldn't have given me a missile silo
>and a few ICBMs to try out procedures on, either. And I really didn't want
>to use the trial-and-error method of learning how to dispose of hazardous
>materials. Oh, and I'm glad I didn't have to use the do-it-yourself-and-find-out-what-works method of research when I was writing survival (desert, mountains, water) manuals.

Although I don't write about airplanes or missile silos or disposing of hazardous waste or how to survive in dangerous places, I also rarely have the luxury of being able to use the products I document.  Very often, I'm hired just weeks before an API is about to be released.  Code is not frozen yet, which means that major portions of things just do not work; they may not even compile.  There is often no GUI to look at.  If I'm hired early on, (planning -- a good thing!) before the API mostly exists, there's little or nothing for me to try out.  

So, for example, I once worked on a product that was supposed to eventually read and generate XML.  I needed an example.  Since I couldn't invoke the product to generate the XML for me, I hand-wrote the XML for my example.  Six months later, when the feature that parsed XML was completed, we ran my XML through it to make sure that my XML was acceptable to the product.  The feature that generated XML was not completed until just before the product was released.

For documenting APIs, I truly believe that one need not use the product in any great depth in order to write about it.  But one does need to understand deeply the process of programming and one does need high quality sources of information and careful reviewers.

My process is: I read the existing docs if they exist and I ask the SMEs if the existing docs are "true" and "complete" (often they are NOT or at least not entirely), I read specs, I look at the code, I interview the SMEs, I might write a sample program or two, especially if I need an example and can't find one written by an expert that shows what I want to show.  

Then, I get someone who knows what they are doing to review every chunk of my documentation.  If I have documented a step-by-step process that I am uncertain about, I specifically flag that passage in the doc I've submitted to the reviewer and ask if it seems right.  I've been lucky (I guess) to have reviewers who DO use the product and try out the procedures I've documented and let me know when they were documented incorrectly.  Also, sometimes I make an error in a document and it is not caught by a reviewer.  It then falls to QA to report my error as a bug.  (Guess it's good it wasn't an airplane maintenance manual, huh?)

But my job is NOT QA -- I don't need or want to find bugs; my job is to document how the product is SUPPOSED to work, when it has been released, not how it does work right at the moment.  If the product did happen to be working properly right at the moment, it would be in release, and my docs would thereby be late.

(Which is not to say that I DON'T find and report bugs; it's just that I don't make discovering them a priority.)

I used to work with someone who called using the product "eating your own dog food".  She was a UI designer and, in her line of work, using the product was one valuable way of learning how others experienced using it.  

But as an API writer -- I KNOW how programmers use the product.  They spend six months to a year or more writing line after line of code, and occasionally calling into the API.  I don't have six months to a year to write an application before I write the manual.  I'm lucky to have six weeks.

On the other hand, if I were documenting -- say, how to make high quality chocolate roses -- I would definitely find the need for hands-on experience.  (And, I'm always open for projects of this kind, by the way...)  

And, I'm in the process of writing a series about building and programming robots: http://www.armadillosoft.com/booksetc/robots/index.php3.  Couldn't possibly write this way without trying stuff out -- it's more like a lab report than a manual.  But then, this project has been on-going for a year and I've only completed a little piece of it.  Not a high-priority/high-profit/high-productivity undertaking.

--Emily

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~                            Emily Berk                                 ~
On the web at www.armadillosoft.com *** Armadillo Associates, Inc.      ~ 
~             Project management, developer relations and               ~
extremely-technical technical documentation that developers find useful.~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com

Sponsored by Information Mapping, Inc., a professional services firm
specializing in Knowledge Management and e-content solutions. See
http://www.infomap.com or 800-463-6627 for more about our solutions.

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.