RE: Technical Writers Needed for API Doc: Really?

Subject: RE: Technical Writers Needed for API Doc: Really?
From: "Susan W. Gallagher" <SGallagher -at- akonix -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 14 Jan 2002 11:38:21 -0800

When I document APIs (I have well over ten years experience
documenting programming languages and did so full-time and
exclusively for about eight years altogether), I always
include a developer's guide. So, no, Victoria, your approach
is not weird.

That said, however, most of the devs I've talked to consider
API docs to be reference. I believe this stems from a dearth
of reasonably good developer guides in the industry. Companies
who one-off their GUI base can get away with providing just
a ref for their API, companies who are in the business of
providing programmer tools wouldn't last a minute if they just
produced reference material for their products.

The attitude that docs for devs don't have to be good doesn't
do a whole lot to improve the genre; and as a group, devs have
had to make due with a lot of crappy docs from writers who
either don't give a damn or don't know how to write a decent
developer doc. I'm always amazed at how appreciative the devs
can be when we spend a little time trying to get the dev guide
in shape.

-Sue Gallagher



>
> At 11:47 PM 1/11/2002 -0800, Andrew Plato wrote:
> ><snip!>
>
> >API guides are mostly raw information
> >intended for a very limited audience that is looking for specific
> >information. API guides don't need to be particularly
> "friendly." Its
> >just a matter of getting all the functions, classes, and whatever
> >documented.
>
And Victoria Camgros answered:
> So, do most of the whirlers agree that API guides==reference material?
>
> When I document an API, I typically develop both a reference
> (classes,
> methods, basic use) and a "programming guide". The latter
> covers the API
> from the POV of programmer's tasks or problems...
>
> So, is my approach weird, or are you all just calling it
> something else?
>

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Collect Royalties, Not Rejection Letters! Tell us your rejection story when you
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of
your book. What are you waiting for? http://www.iuniverse.com/media/techwr

Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ and check it out.

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


Previous by Author: RE: Business cards (was RE: A brief intro and a question)
Next by Author: RE: What should I wear for a phone interview? LONG
Previous by Thread: Re: Technical Writers Needed for API Doc: Really?
Next by Thread: Re: Technical Writers Needed for API Doc: Really?


What this post helpful? Share it with friends and colleagues:


Sponsored Ads