Answer: multiple user roles?, and Question: documenting classes

["John Locke" <mail -at- freelock -dot- com>]

I've got an approach for Shauna's (and Whirler Writer's) organization
questions... and an organization question of my own...

Shauna asks:
> So, with the following combinations, how would you structure a single-doc
> training manual?  (I'm honestly seeking feedback on different and
> preferred
> approaches here.)
> User Q: A, B, E
> User X: A, C(1), D(1), E
> User Z: A, C(2), D(2), E

I suggested a task-oriented structure to Whirler Writer offline. In your
case, you could have some organization such as:

Chapter 1: Introduction. Define user roles, and explain tasks.
Chapter 2: Task A. Users Q,X,Z.
Chapter 3: Task E. Users Q,X,Z.
Chapter 4: Task B. User Q.
Chapter 5: Task C.
   Version 1: User X.
   Version 2: User Z.
Chapter 6: Task D.
   Version 1: User X.
   Version 2: User Z.
Chapter 7: Reference.

For a single manual, this is probably one effective approach (out of many!).
For customized documentation, you could put together some sort of
conditional text that only includes chapters that have the specified user in
some metadata field.


Now for my question. I'm in the midst of a documentation set for an SDK.
Currently I have the documentation organized in the following three
sections:

1. Architectural Overview (describes the context of the entire system, with
diagrams, and a brief description of the role of each class).
2. Tutorial section (describes how to use the SDK to create an application,
then delves into how to code a concrete class that extends each abstract
class).
3. API reference (generated by Doxygen, lists each method for each class).

The problem I'm having is where to describe the existing concrete classes.
For example, the system has an abstract "metadata" class that all "metadata"
objects must extend. The SDK includes two different concrete "metadata"
objects, each with slightly different features and purposes--and the client
developers can develop their own. Currently I'm describing the role of
metadata objects in part 1, and then have a large section describing both
the concrete metadata objects and how to write your own in part 2. But I'm
finding that this section is starting to have multiple personality disorder.

These are objects that need some attention, so I don't want the
documentation buried in part 3. But if I create a new section, breaking part
2 into "coding using the existing objects" and "customizing the existing
objects", now I have "metadata" objects in four different places, each place
in a different context.

Anybody have any suggestions for organizing this so that developers can find
what they need, without getting overwhelmed by 200 pages of overview?


Cheers,
John Locke
http://www.freelock.com


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

Planning to attend IPCC 01, October 24-27 in Santa Fe?  Sign up by
October 3 and get a substantial discount!  Program information, 
online registration, and more on http://ieeepcs.org/2001/

  Your monthly sponsorship message here reaches more than
  5000 technical writers, providing 2,500,000+ monthly impressions.
  Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

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