documentation scope (Re: why o why [off topic])
Stuart Ellis
s.ellis at fastmail.co.uk
Fri Apr 22 10:34:56 UTC 2005
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
More information about the fedora-docs-list
mailing list