[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: proposal for doc rearrangement
Re: proposal for doc rearrangement
Tue, 14 Jul 2009 16:40:30 +0100
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"
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
( - minus, + plus )
- 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
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
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
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.
- 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.