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

[Stuart Ellis]

On Thu, 21 Apr 2005 18:41:42 -0400, "Paul W. Frields"
<stickster at gmail.com> said:
> On Thu, 2005-04-21 at 21:48 +0100, Stuart Ellis wrote:
> > 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.
> 

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

+1.

After trying them out with the software management doc I think that I'll
probably end up putting "Intended Audience" and/or "How to Use This
Document" sections in every tutorial I write.

I also like having an overview Webpage of the Project that doesn't
require opening a document, so I'll probably write some text for one
when we have draft process documents, and post it to see what people
think.
--

Stuart Ellis