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
Attachment:
signature.asc
Description: This is a digitally signed message part
-- fedora-docs-list@xxxxxxxxxx To unsubscribe: http://www.redhat.com/mailman/listinfo/fedora-docs-list
