Re: proposal for doc rearrangement

[Trevor Daniels]

Graham Percival wrote Tuesday, July 14, 2009 10:46 AM


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

Is this always guaranteed?  Actually, all I'm
suggesting is that something like the information
on the Manuals page could sensibly be in the LM,
(and in the other manuals too, for that matter).
Readers can then see where they should go if the
manual they are reading does not contain what
they are seeking.

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

I think it was the latter.

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

Seems at the moment we don't ;)

But you're right.  We need to describe it, and
its limitations.

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

Ah, OK.  It wasn't clear in your original note.

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

I'm happy with that.

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

Well, OK.  It's not an important point.

> Cheers,
> - Graham

Trevor