RE: Starting an API Doc Project

["walden miller" <wmiller -at- vidiom -dot- com>]

There are really two different "top x step" lists depending on when a writer
gets involved in the process.

If the code is done or mostly done (i.e., there is little time to do the
right job):

1. Determine your schedule.
2. Determine if there is JavaDoc/C++Doc/etc. embedded comments in the code.
3. Get direct access to all source code trees included in the deliverable
(e.g., get a Perforce license, an sccs license, whatever tool licenses you
need, and learn to use the code and project tools as a crash project--if you
don't already know them)
4. Collect all specs -- assume they are correct until proven otherwise (you
are on the clock)
5. Determine ownership of code and specs.  These people must become your
friends if they are not already.  NOTE: If you do API docs on a regularly
basis, you should already have many friends in engineering.  If not, go out
to lunch with an engineer.  They don't bite.
6. Use whatever tools you have available to generate the skeleton of the API
reference doc.  There are many auto generation tools that will give you the
functions, parameters, and return values in a format that you can munge,
regardless of whether there are actual comments in JavaDoc/etc. style.
7. Apply your corporate style to whatever you generated.
8. Cut and paste from specs, emails, whatever sources you have to add
detail.
9. Do not wait to complete chapters, libraries, etc. to start review
processes.
10. Repeat 6 and 7 until the deadline is upon you.
11. If your company allows it, acknowledge engineering input in an
acknowledgement section of the manual (use only first names).

If the project is just starting...
1. Work with the Project manager/Engineering lead to ensure you are included
in all project email lists, project meetings, scheduling, code drops, etc.
In other words, make sure you are part of the team.
2. Volunteer to help write and review specs (it is a nice idea, because you
can often use the same API style that you will use in the final manuals,
making cut and paste simple).
3. As code is written, either help write embedded comments or at least write
up the API pages for functions as they are coded.  These will change and
maybe even disappear, but there is something to be said for docs that are
up-to-date with code.  
4. Point out when code changes that does not match the spec.  Offer to
update the specs to match the code, if that is the decision by the project
team (it usually is).
5. Work with the Product manager on putting together all the ancillary docs
and product material.  This is just good politics for when the crunch comes
later.  
6. Be friendly to the project team.  They are in the same boat you are.
7. Use your standard writing department processes as best you can (see the
above list).  When they get in the way of engineering processes, defer to
engineering whenever possible.  This is a political move.  BUT, do not
sacrifice quality of docs to engineering processes.
8. If your company allows it, acknowledge engineering input in an
acknowledgement section of the manual (use only first names).

Usually, the process is somewhere in between these two.  Vidiom is currently
in the throws of writing a gargantuan API project (5000 page API reference
manual + equivalent programmer's guide and tutorials-- we ought to top out
in the 8000-9000 page range).  We started working from the beginning with
the project team, but it has felt like a crash project from day one.  Much
of the code was licensed from SUN and other vendors with little to no
documentation, so we have been playing catch-up for a year.  The deadline of
Q204 looks very tight.  Consequently, all the friendships and politicking
has paid for itself many times over.   

Hope this helps.

Walden Miller



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ROBOHELP FOR FRAMEMAKER TRIAL NOW AVAILABLE!

RoboHelp for FrameMaker is a NEW online publishing tool for FrameMaker that
lets you easily single-source content to online Help, intranet, and Web.
The interface is designed for FrameMaker users, so there is little or no
learning curve and no macro language required! Call 800-718-4407 for
competitive pricing or download a trial at: http://www.ehelp.com/techwr-l4

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