RE: Technical Writers Needed for API Doc: Really?

["John Locke" <mail -at- freelock -dot- com>]

Cedric also posted this to the NetTechWriters list, and I answered
there, too.

But that discussion has taken a different tack, so I'm going to rephrase
my answer here.

You need a writer for the big picture. Developers are great for
documenting each object, each interface, what needs to go in, what needs
to come out. But in my experience, few of them care to write about how
objects relate to each other, and why you would want to use each object.

As a writer you can add value by taking the spec (if there is one), a
list of the objects and interfaces, and sitting down with the developer
with the following discussion:

Me: "Okay. So tell me about object zifraxibobble. What is it's reason
for living?"
Developer: "Well, you need zifraxibobble to handle restrictions for
brshingdell." Embarks on long discussion of how it all works.
Me: "So let me get this straight. The brshingdell object creates a
zifraxibobble... When?"
Developer: "When it gets a new request that doesn't have a valid framm
struct."
Me: "And the framm struct does such and so."
Developer: "Yes."
Me: "But what happens when the zifraxibobble dies? Who is responsible
for clearing the memory for the framm struct?"
Developer: "Uh, Oh yeah! I forgot to put that down. The xyzzif object
relies on that struct for something else. The brshingdell object creates
all of the framm struct, and has a function for deallocating its memory,
but your application must call that function only after you know you're
done with it.

These are the kinds of details developers don't write down. You have to
drag it out of 'em. And you have to know the questions to ask to do
it--which means studying the APIs ahead of time. Do your homework first.
But when I started documenting C++ interfaces, I didn't know a struct
from an object constructor. What did I do? Apologize for my ignorance,
and ask: "Okay, this may be a stupid question, but I'm not familiar with
structs. What exactly is a struct?" Even if you already know the answer,
the way the developer answers it in the context of what you're writing
about may illuminate things that are worth explaining to your end users.
And I've never had a developer complain about my lack of knowledge of
the innards of C++ ... Often, it turns out that what I'm asking about is
some sort of thing they created internally, that your external developer
audience certainly needs to know about.

Afterwords, you just write it all down, and create diagrams to
illustrate how it all works. Visio is a great tool for this--learn some
UML to go with it.

Without a writer organizing all of the overview information, and
highlighting the parts of the APIs that the audience needs to get
quickly started, the poor sops who have to use the API have to work
through all of the objects, all of the interfaces, just to write a
simple program that uses it.

Seems to me that the writer brings great value to this process. Not in
documenting each interface--rather in showing someone what to do with
it. 

Cheers,
John Locke
http://www.freelock.com


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Attention ForeHelp and Doc-to-Help Users! Upgrade your existing product to 
RoboHelp for FREE, through January 15th. RoboHelp can import your existing 
Help projects! Learn how else RoboHelp can benefit you. www.ehelp.com/techwr

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