LilyPond Grand Documentation Project (GDP)

[Graham Percival]

I am proud to introduce the LilyPond Grand Documentation Project!


It's been said that we have some of the best-organized docs of any
open-source project. I'm happy to accept this praise -- and I think
it's true -- but this only applies to the *organization*. When I look
at our table of contents, I'm (mostly) happy with it.

When I look at a specific section of the docs, I'm not so happy.

About 75% of the "* Notation" sections have not been touched in the past
three years. A lot of things are out of date -- with LSR avilable, we
need to add tons of links to it. We could use more @seealso. We should
move lengthy explanations into the Learning Manual. Review @refbugs
warnings, add more @rgloss, improve consistency etc. I could go on and
on. But there's no point listing all the problems, unless something
will actually be done.

I'd like to have a dedicated, limited-term project to work on the docs
-- say, the next 4-6 months. But I'm not going to do any more boring,
trivial changes. What do I mean by "boring, trivial"? I mean a task
that I can explain to my mother in 5 minutes. My mother knows nothing
about lilypond and little about computers. But if I tell her "in this
text file, make sure that @seealso occurs before @refbugs in each
section", she'll be able to make those changes.

So if we're going to fix any of those problems, it needs to come from
user volunteers. I feel justified in saying this: I estimate that I've
spent about 500 hours doing such changes. I've spent enough time doing
trivial text editing.

I'm looking for volunteers to help with the Grand Documentation Project.
This may be of particular interest to translators: it might be a good
idea to improve the English documentation before translating more of
them. I've discussed this with John a lot, and he can add more details
about how this affects you.

The scope of GDP really depends on how many people volunteer. If it's
just me and John, we'll rearrange the subsections and leave it at that.


I have a list of stuff I'm hoping to have done; I broke them down by
difficulty and listed the estimated times.


TRIVIAL (do these while in a university lecture, listening to music,
etc)

- standardize order of @seealso, @refbugs, @commonprop. Add @lsrdir{}.
Standardize # signs.
- probably more

Total: 30 hours, easily split into small chunks (ie different people).


EASY (some knowledge of English required, but can still do while watching
Battle Star Galactica or listening to music)

- avoid future tense / general consistency.
- do the current docs make sense?

Total: 20 hours, easily split into chunks.


MEDIUM (ability to write lilypond examples, discuss on mailist. Do
these while watching old anime you've seen before)

- improve lilypond examples in the manual. Possibly with some kind of
musical / melodic sense. Move nice LSR examples into the manual.
make new lilypond examples for @commonprop.
- add links from manual to the glossary
- add more translations to the glossary, possibly examples as well
- remove non-verbatim examples from the docs
- add special non-verbatim inspirational "headword" examples.
- new docs for some items

Total: 40 hours, can be in chunks


HARD

- rearrange sections.
- rewrite current docs if necessary.
- oversee work in trivial, easy, and medium.
- new docs for some items

Total: 40 hours, could be split into two or three chunks


Given this list, I'm only interested in doing hard items. If you're
interested in doing anything from this list, please reply. The amount
of work depends on user interest -- and I mean "the willingness of users
to help", not "yeah, that sounds like a great idea! I'll take a look
when it's finished".

My current plans require at least six users willing to spend at least
two hours a week on this. If there's more people helping, we can do
more. If there's less, we'll do less.

Cheers,
- Graham Percival, LilyPond Documentation Editor