TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
(Belatedly, as I clear the decks preparatory to taking a few days off...)
Suzi Magill wondered: <<Is there a site, book, anything on how to start
documenting APIs? I have never documented one before and am looking for a
good starting point...>>
This has been discussed a few times in recent years on techwr-l, so have a
look in the archives (at www.raycomm.com) using the search word "API". One
thing you might want to consider is talking to the developers of the API
and asking them how they use such references in their own work: what they
like, what they don't like, what they'd really like to see that nobody else
has done yet. That's a great start, since the odds are good that they're
fairly representative of your audience. Of course, so much the better if
you can talk to the real audience.
I don't have any firsthand experience with documenting APIs, though I've
used several in the past and thus have some opinions on what works well and
what doesn't. But a colleague of mine in Montreal, Manny Gordon, has given
a course on this topic a few times, based on direct experience in the
trenchees, to good reviews from all I've heard. I know that Gordon and
Gordon (his company) also sells the workbooks from their courses, so it's
quite likely you can pick up the workbook online via their web site
(www.gordonandgordon.com). I've taken a couple of their courses and
profited from them, so it might be worth your while seeing if you can stir
up enough interest in your area to get the terrible twosome to come give a
workshop.
Disclaimer: I've known Manny and his partner Gordon Graham for many years
now, so I'm biased. <g> But on the other hand, STC's Montreal chapter has
been bringing them back for a couple workshops per year for several years
now, and they keep filling the room. So take that as independent
confirmation of the quality of their work.
--Geoff Hart @8^{)} ghart -at- netcom -dot- ca
"Arthur C. Clarke had suggested that any sufficiently advanced technology
would be indistinguishable from magic--referring to a possible encounter
with an alien civilization--but if a science journalist had one
responsibility above all else, it was to keep Clarke's Law from applying to
human technology in human eyes."--Greg Egan, "Distress"
*** 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 Cub Lea, specialist in low-cost outsourced development
and documentation. Overload and time-sensitive jobs at exceptional
rates. Unique free gifts for all visitors to http://www.cublea.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.
