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
_______________________________________________
lilypond-devel mailing list
lilypond-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-devel
