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

[Paul W. Frields]

On Fri, 2005-04-22 at 11:34 +0100, Stuart Ellis wrote:
> 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.

Before you put in all those changes, please check out my mirror-
tutorial, which implements a lot of this in a way that was previously
discussed and ratified on-list.

  http://docs.frields.org/html/mirror-tutorial-en/

Try and make your front chapter as close to this in appearance and
structure as possible.  There's a Purpose section, Audience section, one
or more About sections (one for each of the *most* major technologies
your tutorial discusses), an Additional Resources section, and an
optional Acknowledgments section.  

I'll start a new thread about this as soon as I can figure out what I am
able to start doing with the Documentation Guide.  I've put this on our
wiki DocGuide TODO list, tied in with the "provide example tutorial to
learn while doing" bullet:

  http://fedoraproject.org/wiki/DocsProject/DocumentationGuide/


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

Like this?

  http://fedora.redhat.com/projects/docs/

You could start with that and suggest changes from there.  You can check
this stuff out from CVS in the "/cvs/fedora" tree (as opposed to
"/cvs/docs" or "/cvs/extras," although you will have to file your
changes as a patch in Bugzilla.  It would be much appreciated; the front
page on f.r.c is getting out of date as we speak... tick... tock...  :-)

Seriously though, we should start figuring out ways to take some of the
load of the few Red Hat employees, who, after all and just like most of
us, don't get to spend all day just diddling with Fedora Project stuff.
Your offer to do that is just what the doctor ordered, methinks.

-- 
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: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20050422/722f39ff/attachment.sig>