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.
Answer: multiple user roles?, and Question: documenting classes
Subject:Answer: multiple user roles?, and Question: documenting classes From:"John Locke" <mail -at- freelock -dot- com> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Thu, 4 Oct 2001 08:46:53 -0700
I've got an approach for Shauna's (and Whirler Writer's) organization
questions... and an organization question of my own...
> So, with the following combinations, how would you structure a single-doc
> training manual? (I'm honestly seeking feedback on different and
> 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
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
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?
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.