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 7/1/05, siliconwriter -at- comcast -dot- net <siliconwriter -at- comcast -dot- net> wrote:
> 1. Does one generally incorporate the APIs themselves into a developer's guide? I can do this only with the 3 docs I have right now; if I have to go in and EXTRACT the information from the 8 APIs in our Service Pack, it will take, well, months. Also, that would make a very long book.
Nah, don't do that. As you've surmised, you'll have to convert
everything, the book will be huge, and then you'll be working from
second hand information and the minute anything changes your
maintenance task will be a nightmare. Keep the API reference docs in
the source. Distribute them in HTML. Developers are used to that.
> 2. If it is not usual to incorporate the APIs in the developer guide, what DO you put in a developer guide?
Think of the overall SDK documentation as being like a set of car
manuals for mechanics. Your API reference is like an alphabetical
list of car parts. So you've got your pistons and your crankshafts
and your valves and your timing chains and whatnot. And the parts
list may be very helpful in explaining that the thing with the wires
and tubes is the fuel injector, and it takes gas in one end and blows
out gas mist from the other -- but there's nothing in the parts list
that explains that the engine is what makes the car go or that gives
you a list of steps for how to change the oil in the car.
The developer's guide, therefore, has the bigger picture for the SDK.
It should explain how all the parts fit together and how the SDK
product fits into any bigger architecture (.NET, Java, etc, etc).
There will probably need to be a bunch of task-oriented docs for the
major things that a developer will do with your SDK. And, unlike a
car manual, there will also probably need to be a whole lot of sample
programs that demonstrate the major tasks. Those programs will need
to be documented and explained as well. Unless you are yourself a
programmer you're going to need a lot of help from your SMEs on most
of this -- its a tough job.
>Do you refer the reader to the (separate) APIs? How would you refer
them to a Doxygen suite of HTML pages?
Within the developer's guide you can just refer to the API reference
implicitly. You might say something like "To connect the Barzort
widget to the network, use a Froznob object. For example:
In this example, the Froznob class was instantiated with the parameters:
+ 1 for the number of connections
+ "pow!" for the connection type, indicating a fast connection
+ true to create an infinite socket
For more details on the options for instantiating the Froznob class,
see the online API reference."
This is, of course, a ridiculous example (I am a master of the
ridiculous example). But my point is that in the developer's guide
you can just give a general example of common use and then refer to
the API docs for more specific details.
Hope this helps,
Laura
ridiculous examples 'R' us
--
*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^
Laura Lemay Killer of Trees lemay % lne.com lemay % gmail.com http://www.lauralemay.comhttp://blog.lauralemay.com
*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^
Now Shipping -- WebWorks ePublisher Pro for Word! Easily create online
Help. And online anything else. Redesigned interface with a new
project-based workflow. Try it today! http://www.webworks.com/techwr-l
Doc-To-Help 2005 now has RoboHelp Converter and HTML Source: Author
content and configure Help in MS Word or any HTML editor. No
proprietary editor! *August release. http://www.componentone.com/TECHWRL/DocToHelp2005
---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit http://www.techwr-l.com/techwhirl/ for more resources and info.
