Rohit recommended this to me, and it's a decent read about user
documentation for software. I especially like the 3-stage model
in the "method" section:
> In a commercial environment, the production of reliable documentation
> falls into three distinct stages. While this paper discusses them
> sequentially for the sake of simplicity, the pressures of real-life
> project development often force variations.
>
> For instance, on a project with tight deadlines, some stages overlap in
> a pipeline. A partially-completed data analysis can be used to start
> developing examples, and early sets of examples can be placed in a
> tentative order so that the writer can start creating the text.
>
> Changes in design or marketing strategy also complicate the method by
> requiring the team to reiterate completed stages. If a new feature is
> added, each of the documents produced in each stage must be adjusted to
> include the feature. One of the method's strengths is that writers can
> quickly determine the ripple effect of any change on the entire user
> viewpoint, and make incremental changes to documentation where
> necessary.
>
> Stage 1: List and Categorize all Data Items Affecting the User
> Stage 2: Develop Examples
> Stage 3: Order the Examples
Particularly useful is the classifications in stage 3.
> This stage organizes the examples of Stage 2 into a structure that
> determines the order of presentation in the final document. The
> structure has elements of both a simple linear ordering and a tree
> hierarchy. The linear elements will be more evident in a printed manual,
> and the hierarchical elements in on-line documentation.
>
> Stage 3 continues the movement started in Stage 2, away from the
> structure of the software and more toward the human user. The goals are
> to make it as easy as possible to get started with a product, and then
> to identify and incorporate useful enhancements. Examples provide
> natural criteria for ordering information in a linear fashion:
>
> Simple applications before complex ones. Start with the simplest
> possible example of product use, and try to introduce only one or two
> new features in each successive example.
>
> Common features before obscure ones. Special options that fulfill
> rare needs can be isolated near the back of the document.
>
> The hierarchical aspects of organization come from the models and
> tasks discussed under Stage 2. These help to group together the
> examples that users need at a particular time.
>
> The result of Stage 3 is a re-ordered set of examples organized under a
> hierarchy of tasks. Since it represents the final structure of the
> manual, reviewers can examine the hierarchy to decide whether features
> are presented in an appropriate order and given the right amount of
> attention.
>
> At the end of this stage, the engineering team has formally defined both
> the topics and the structure of the product's documentation. The
> richness and authority of the information that this resource offers to
> technical writers cannot be matched by any other method. Writers can now
> prepare background information and narrative text that explains the
> models, tasks, and techniques. The cross-referencing system can be used
> to build the index.
>
> As a brief example of a document structure designed through data
> analysis, here is the outline for an on-line, fully task-oriented
> description of ANSI C and POSIX signals [ANSI, 1989; IEEE, 1988] .
Yes, Rohit, I now understand why narrative threads are so important.
----
adam@cs.caltech.edu
Jack Ryan as President manages to declare martial law in the U.S.,
triple the size of the CIA operations directorate, lobby for a flat tax
system, order the assasination of a foreign head-of-state, state
publicly that he is against abortion, and most amazing of all, get
public apologies from journalists who misrepresented him. Whew. Busy
guy. Clancy also unsubtly shows a terrorist taking advantage of
encryption and the internet to carry out his nefarious schemes. Thank
goodness the FBI can still break into houses and get telephone records
without warrants!
-- Greg Titus. Senior Software Wizard at Omni Development