documentation scope (Re: why o why [off topic])

[Paul W. Frields]

On Thu, 2005-04-21 at 21:48 +0100, Stuart Ellis wrote:
> On Thu, 2005-04-21 at 12:48 -0700, Karsten Wade wrote:
> > > Do we have an existing document that could cover policy for
> > > scope/lifecycle of docs (what we accept, how we support it, process of
> > > obsoleting old work) ?  These issues don't seem to neatly fit just Quick
> > > Start, Documentation or CVS Usage.
> > 
> > I see this as the Documentation Guide.  It is one of our few monolithic
> > documents.  It could contain everything about this project, process,
> > lifecycle, workflow, how-to, what-is, etc.
> > 
> > Making separate or joined documents is just about the same thing.  Since
> > it's already there, I'm in favor of adding to the Doc Guide as the
> > canonical for All Things FDP.
> 
> OK.  The current version of this is primarily technical (DocBook/CVS
> use), but of course it's due to be revised anyhow.

Like with a Style chapter!  (Hint, hint, certain editors...)  ;-D

> The only thing I'd add is that big documents can look imposing just by
> their size...  I like the way that the current Docs Project site has a
> relatively short, action-orientated page ("to get contributing, do this,
> then this and then this"), although I agree that the existing content of
> the Quick Start Guide page ought to be part of the Big Book of
> Documenting.

I think big books can be made much less scary when the very first thing
that appears in them is a demystification of what's in the rest of the
book.  Let me give an example.

I have a neat little musical gadget that came with a user manual.  This
gadget is designed for ALL musicians, not geeky ones, and is used by
many famous people who are not geeks themselves.  The manual starts with
a chapter, 1-1/2 pages long, that should basically be (and, in fact,
roughly *is*) "If You're Impatient, Read Only This Before You Plug in
and Start Twiddling Knobs."

If the Doc Guide has a *VERY SHORT* chapter up front that serves
something like this purpose -- i.e. "Don't Be Scared of This Guide;
Here's What It Contains in a Nutshell" -- it would be more accessible to
all without having to dumb down the entire guide.

Just an idea... I will try and Wikize this if/when I get a chance
tonight.

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : http://lists.fedoraproject.org/pipermail/docs/attachments/20050421/8ee4d396/attachment.bin