Re: proposal for doc rearrangement

[Graham Percival]

On Sat, Jul 11, 2009 at 12:01:22PM +0100, Trevor Daniels wrote:
>
> ----- 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".

For the sake of argument, assume that users always see the new
website Manuals page.  What else should users see?

- I agree that we should encourage them to click on HTML images,
  but that's done in the tutorial.
- I'm not certain if we should mention that the mailist archives
  are a for of "documentation", but if you think that's important,
  I don't mind keeping that somewhere.  I might make it more
  prominent on the web Community->Contact page, though.
- init files: this is only applicable to tweaking, but IIRC that's
  in the LM already.

Basically, I think that LM 1.2 wasn't a success.  Either because
users didn't notice it (since the "jumping in point" was LM 2), or
because it included *too much* information.  Nobody could get a
sense of the docs at glance.

>> + expand 2.1.1 Compiling a file into:
>>   + LM 1.1 Compiling with LilyPond and LilyPad
>
> Do we want anyone to use LilyPad?

If we still ship it, then we should describe it.  For Windows and
OSX; the linux version just has the command-line.

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

I'm fine with changing the title.  My hope is that they'll have
read Text Input before they see the LM, but you're right that we
shouldn't assume they have any info before they read the LM.

>>   + LM 1.2 Alternate editors
>
> Not a suitable name if setup stuff is coming here.

The OS-specific setup (which IIRC is only for osx) is going on the
Download page, so this section really _will_ be for alternate
editors.

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

Ok, that's fine with me.  I'm also thinking that the LM could use
a short conclusion (mainly pointing out the other parts of the
docs that should be consulted next), so we could keep a short LM 5
with some old material and a conclusion.

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

IMO, that deserves to be on the website on the Download pages
(again, assuming that it's available in pdf+info forms for those
who prefer such formats).

Cheers,
- Graham