State of the docs, April 2006

[Graham Percival]

Hi all,

I'm getting burnt out from trying to do all the documentation.  In 
addition, in a fit of insanity I agreed to be the new Bug Meister.  To 
give me time to do the Bug stuff, we need more people working on the 
docs.  I also have major doc changes that I've wanted to make for 
almost a year now, but they keep on getting postponed due to more 
urgent doc stuff.

I'll be making an appeal on -user soon for more help (I wanted this 
email to get archived first).  Working on the docs requires no 
technical knowledge, and in some ways a lack of lilypond experience is 
a plus.  I'm not asking for diff files against CVS (although those are 
nice); all I require are very clear emails.  See
http://lilypond.org/web/devel/participating/documentation-adding

Several people have been giving me help with the docs, and I'm very 
grateful to them.  I'm just hoping that they, and others, will be able 
to do even more.  :)    I have discussed a few of these items with some 
of them.  I haven't forgotten about it, but it's up to you whether you 
want to step forward publicly with your offer.


Here's a list of documentation tasks, in order of my desire for 
somebody else to tackle it:

MAILIST DATA-MINER
Lilypond knowledge required: minor
Estimated time: 2-4 hours per week.

Somebody needs to monitor lilypond-user (and ideally -devel as well) to 
find things that should be added to the docs.  It may be a particularly 
informative email from Mats or Nicholas, or it could be the fourth 
person asking for clarification of the same issue.  This is a good way 
to learn about lilypond -- you'll quickly cover a wide range of the 
docs, but only in little pieces.

Note:  I am *not* asking for somebody to send me these informative 
emails.  I need somebody who will read those emails, read the 
documentation, decide what to add/remove/replace in the documentation, 
and send me the instructions about *exactly* what to 
add/remove/replace.


UPDATING MANUAL WITH NEWS   -- taken by Cameron Horsburgh
Lilypond knowledge required: moderate
Estimated time: 10 hours (total, not per week)

Some info from the NEWS files has failed to make it into the manual.  
Somebody needs to check the old NEWS files for info that should be in 
the manual, and then write docs for the items.  Other people are more 
than welcome to help write those docs, of course.  :)
Cameron will be sending en email soon with more details.


INSTRUMENT-SPECIFIC NOTATION
Lilypond knowledge required: moderate knowledge in a specific area
Estimated time: variable

As far as I know, the "instrument-specific notation" chapter is ok as 
it is.  However, if there are problems, I'm not going to fix them.  I 
don't play those instruments, I don't write music for those 
instruments, I don't know what music for those instruments should look 
like, and in the near future I won't have the time and energy to find 
out.

If you use any of the notation listed in this chapter -- including 
lyrics, which I know is a big use of lilypond -- then please consider 
"adopting" the appropriate section of this chapter.  If anything needs 
to be clarified, or if new notation should be added, please write it 
yourself.  If you use figured bass, or play guitar, or whatever, then 
you know more about using lilypond for such things than I do.  I'm 
still quite happy to do the technical step of translating specific 
instructions from an email into the lilypond documentation, but I am a 
poor choice for writing these docs.


CHEAT SHEET
Lilypond knowledge required: minor
Estimated time: 2 hours

We have a "cheat sheet" (appendix E, I think).  Currently I think it's 
a bit useless; it doesn't have a lot of info in it.  It would be nice 
if we had more info on it.


TIPS AND TRICKS
Lilypond knowledge required: moderate
Estimated time: 10 hours

Somebody should go through all the examples in "tips and tricks" and 
make sure they all work (and fix them if they don't!).  This is 
somewhat of a nostalgic proposal for me, as this was how I began doing 
doc work for lilypond.  This is also a -fantastic- way of learning 
about some of the wacky and really cool features of lilypond.


TEMPLATES
Lilypond knowledge required: moderate
Estimated time: 5 hours

Do all the templates in chapter 3 work?  I know that the "Jazz 
ensemble" one is very old, and is generally icky.  If nobody updates 
it, I think we should just delete it.  I don't know what the status is 
on the other templates.  In addition, all the templates should follow 
the same general style.


SCHEME / MUSIC EXPRESSIONS EXPLAINED
Lilypond knowledge required: lots
Estimated time: 5 hours?  10?

Many people have asked for clearer explanations of music expressions 
and scheme.  Such documentation will not be coming from me within the 
next two months, since I don't understand this stuff either.  If enough 
people take over the daily doc stuff (such as mailist data-miner), and 
once I finish my other tasks, I'll certainly tackle this one.  But only 
after I finish other stuff.



INTERNAL ENGINE DOCS
Lilypond knowledge required: even more than lots.  Tons.  Oddles.  You 
get the idea.
Estimated time: I have no clue

Some people have asked for documentation about "the working of the 
engine (the interaction, passes etc. of scheme python, C, TeX, pdfwrite 
...)".  I barely understand the question, let alone the answer.  I 
_might_ be able to write documentation about this in two or three 
years.  If you want it sooner, volunteer.


START-TO-FINISH EDITING
Lilypond knowledge required: moderate
Estimated time: depends on thoroughness

I'm not really looking for somebody to do this, but if you want to 
offer, great!  This involves reading the whole manual and making minor 
fixes as you go -- typos, grammatical mistakes, maybe re-writing a 
paragraph or two, adding new links, etc.  I plan on doing this in about 
a month, but it doesn't hurt to have more than one person looking for 
such mistakes!



In case you're wondering what's left for me to do, here's my list (in 
order of priority):
1)  Function as a human email-to-CVS gateway.  If anybody sends me 
clear instructions for the docs, whether or not they've signed up for 
one of these jobs, that has my very highest priority.
2)  Be the mailist data miner, if nobody else does.  :(
3)  Do any NEWS file updates if there are things left over that nobody 
else takes.  :(
4)  Move chapter 3, probably into an appendix.  Increase visibility of 
chapter 4; add info about style sheets, versioning control, 
preprocessors, whatever.  I'll probably rename chapter 4 to "Working 
with lilypond files".  This is always a fairly hot topic on 
lilypond-user, but I haven't had time to write the material.  Hint: if 
you'd like to see those docs, check out items 2 and 3, and make sure 
that I don't have to work on them.  :)
5)  Work on integration with LSR.
6)  Revisit "global issues", specifically with regards to horizontal 
and vertical spacing.  I know that some kind of awesome system-spacing 
stuff was added in 2.7, but I don't know what it is, nor do I think we 
have good docs for it.
7)  Revisit "chanding defaults"; I think that I could make it much 
easier to understand.  Time, time, time...
8)  Start-to-finish editing.  As part of this, I'll be making a 
separate "command index", which only contains entries for \commands in 
the manual.
9)  Work on scheme/music expressions, if nobody else does.  :|   (I 
won't be unhappy to do this, since I should learn this material anyway, 
but it will only come after everything else on this list)

I've probably forgotten a few things, but as you can see, I still have 
a lot of things to do even if volunteers step forward to do everything 
I've asked for.


Please consider helping the LilyPond project by doing one or more 
documentation tasks.  I'm quite willing to spend time helping you with 
any difficulties you might have in doing these tasks.

- Graham Percival, LilyPond Documentation Editor