Re: comprehensiveness and completeness of large docs

[Dan Mueth <d-mueth uchicago edu>]

On Wed, 9 Aug 2000, Aaron Weber wrote:

> So, in working on docs for large apps, one tends to run into the problem
> of being comprehensive.  It's easy enough to describe every feature of a
> smaller app-- you can just run through the menu bars and toolbars and
> you're done.  The menu bar section goes at the end of the manual, after
> the window sections, like in the template.
> 
> But for Evolution, I'm having a little conceptual trouble.
> 
> Do I put all the menu-bars in big appendix as a reference of all
> functionality, sorted by component and indexed by task?  Or should I put
> a menu-bar section at the end of each window description?  How about
> just making sure that everything is covered somewhere and having a
> really good index?
> 
> I'm leaning towards the second most of the time, and towards the first
> one some of the time.  The third just seems too hard to keep track of. 
> What say ye?

Allow me to offer a fourth method.  You write your document as you would
normally, not putting too much effort in describing all of the interface.
(This will make the document readable and it will flow smoothly, focussing
on concepts, not interface.)  Then add an appendix which covers all of the
interface components(even if they are discussed elsewhere).  This could
even be similar to an index in that it can reference places in the text
where particular components are discussed. This doesn't make things any
easier for the author (you).  However it will make things very easy for
the user since all of the interface components are described in one place
and there are even links there.  I think this is possibly an extremum of
work for you and ease of use for the user.  Since the links are
conceptually similar to an index, you may be able to leave this work for
one of our indexers.

Dan