RE: Damnit Jim, I'm a Writer, not a Programmer II: The Wrath of Khan

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

On Mon, 9 Jul 2001 10:12:25 -0400, /kevin wrote:
>All you list-members whose job description includes a significant amount of software QA, please stand up.

I'm standing tall (and that's hard for me, as I'm under 5 ft.)  When there's a bug lodged against an API, it's either a software bug or a documentation bug.  (In other words, either I incorrectly described how to use a function or the function changed and no one notified me or the function was incorrectly implemented.)  So, I would say that QA takes up a good 25% of my steady-state time (that is time after the initial documentation is done).  Usually, if I find something that I think is wrong, I don't go and immediately change the docs; I ask an SME first.  But I do spend significant time finding out what's wrong.

>...When I include a chunk of code in a toolkit or API doc, I don't make it up. I get it from the development team. I copy and paste, precisely so that I won't introduce any thumb-generated errors.

IME, getting code from the development team doesn't mean that:

1.  The code is actually correct (would compile and run)
2.  The code actually does what the developers claim it does and in the 
    way the developers want USERS to do it
3.  The code is useful

Whenever I get code from anyone, I read it.  I often find something wrong with it.  It's usually something simple, like, it's missing a final semi-colon.  But sometimes, the code actually does not do what the programmer claims.  Or, it does what it claims but it doesn't do it the way the programmer had told me to explain how to do it.  And, sometimes, it's so poorly designed/written that it is not appropriate for printing in an API manual.  (e.g., it looks like: fprintf(urt, "%f.6 %s " , dr, (i=0;1+%r\d;++i));)  

And you almost always want to add/edit the comments in the code to explain what each important line does.  And you want to remove all the lines that are irrelevant so they are not confusing to the reader.

In order to be able to do all this, which I think is necessary if you are going to be documenting CODE, 

           then you do need to be able to read and understand code.  

On the other hand, if you don't publish code in the manuals you write, well, then, obviously, you don't have to worry your little head about this.

--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

TECH*COMM 2001 Conference, July 15-18 in Washington, DC
The Help Technology Conference, August 21-24 in Boston, MA
Details and online registration at http://www.SolutionsEvents.com


---
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.