Re: proposal for doc rearrangement

[Trevor Daniels]

Graham

In general, this looks good.  More below ...

Trevor

----- Original Message ----- 
From: "Graham Percival" <address@hidden>
To: <address@hidden>
Sent: Saturday, July 11, 2009 11:14 AM
Subject: proposal for doc rearrangement


> Here's my proposal for doc rearrangement from a doc writer's
> perspective.
> ( - minus, + plus )
>
> LM
> - background essay
> - about the docs    (nobody reads it there, anyway)

I'd still like to see some sort of overview of the
available documentation early in the LM.  Perhaps
just the "About the Learning Manual" section with
a reworked list like "About the documentation",
perhaps renamed "Other documention".

But drop the rest of the "About"s.

> + expand 2.1.1 Compiling a file into:
>   + LM 1.1 Compiling with LilyPond and LilyPad

Do we want anyone to use LilyPad?

Don't like to use "Compiling" in a heading.  It
will not be understood by computer-non-literati.

>   + LM 1.2 Alternate editors

Not a suitable name if setup stuff is coming here.

> - (possibly) Working on LilyPond Projects

Quite a bit of the material here is suitable for
the LM, but the organisation is poor.  (We didn't
get to this during GDP).  I think we might need
to dissect it, with bits staying and bits going to
the AU.

> Essay
> + background essay
> + essay from website.  (maybe merged, maybe separate)
> + literature list
> + anything else scholarly

Tick

> NR
> - literature list
>
> AU
> - install, compile.  (that'll be in the CG and available as
>  INSTALL.txt in source)

Should not the simple instructions for installing
GUB-built binaries remain?

> - setup  (separating into website and LM 1.2)

Probably better in the LM.  Might help to direct
new users there at the start.

> + (possibly) Working on LilyPond Projects

Parts of, yes.

> +- rewrite lots
> + (possibly) guides ("how to use lilypond to X"), maybe
>  algorithmic music, etc.  There's always been some interest in
>  this, and it doesn't fit in to the LM or NR.
>
>
> I think the only iffy proposal here is moving LM 5 Working on
> LilyPond Projects.  It's partly because I can't find it in me to
> blame newbies[1] who don't notice LM 5 and ask stupid questions
> later, and partly just to beef up the AU so people don't
> completely ignore it.  I'm not completely certain about that
> change, so opinions are welcome[2].

OK, some above.

> [1] this is always my primary concern when organizing the docs.
>
> [2] although I feel quite good about all the other changes,
> opinions are still welcome.  In the words of one of my
> supervisors, "feel free to disagree with me.  You'll be wrong, but
> feel free to disagree!"
>
> Cheers,
> - Graham

Trevor