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.
On Tuesday, January 20, 1998 9:16 PM, Sella Rush
[SMTP:SellaR -at- APPTECHSYS -dot- COM] wrote:
> Does anyone know of any resources on putting together the documentation
> for an SDK? We did the first draft of our SDK recently, and while all
> the programmers (including a contractor newcomer) think it's just fine,
> the organization seems almost incoherent to me. I can't seem to get a
> handle on specifics of the audience and what they need from the
> documentation. Also, I'm having trouble drawing conclusions based on
> existing SDK documentation. (There's a key out there somewhere that
> will make everything fall into place--I just need to find it!)
>
> Do many people have to write SDK documentation or is it a rare task?
I wish I had a good reference on writing SDKs -- man, do I wish! Apart from
writing one myself, which may happen, I haven't found anything other than
other SDKs (Software Developers' Kits) and each one is different in scope
and organization. True, SDKs are very much custom documents. They provide
information for other developers who want to integrate our tools and
products with their own, as well as build third party products based on our
code. Accordingly, an SDK has a hefty price tag and is often part of an
alliance or partnership agreement.
Sometimes, SDKs are merged with API (Application Programming Interface)
documents, the goal being to provide whatever information is necessary for
another developer to be able to take our stuff and make it sing in their
environment.
Getting a handle on the audience is tricky, because we rarely know what the
"end users", in this case programmers, need from or intend to do with the
information. I think as long as you provide a What, How, Why approach,
you'll cover most of what they need to know. The organization of the
document is pretty much up to you, and it's dependent upon the information
you are including. As long as you apply good techwriting skills to the
thing, you can't go far wrong. I don't think the users are likely to want
to read it cover to cover, anyway.
Writing the SDKs and API documents are the most technical part of this job.
I enjoy the challenge, and after putting together a couple of them in the
last year, I've gained a greater appreciation for our own developers.
--Beth
Beth Agnew
Senior Technical Writer, InSystems Technologies Inc.
65 Allstate Parkway, Suite 100 Tel: (905) 513-1400 ext. 280
Markham, Ontario, Canada L3R 9X1 Fax: (905) 513-1419 mailto:bagnew -at- insystems -dot- com Visit us at: http://www.insystems.com
