CHECKLIST FOR DOC SECTION REWRITES

You've volunteered (or are considering volunteering) to edit a
section of the NR.  Congratulations!  You'll learn a lot about
this part of lilypond.  You'll also get thoroughly fed up with
documentation work, and especially with me... but as they say,
"you can't make an omelett without breaking a few eggs".  Welcome
to egg-hood!

REQUIRED READING

- policy.txt
- writing-texinfo.txt
- this document :)
- NR 1.1 Pitches.  Ideally, read it in your favorite output format
  (either info, PDF, or HTML), *and* in source format
  (pitches.itely).  This is our "demonstration" chapter, so the
  below points really just boil down to "make it like
  pitches.itely".


WORKING

I recommend working on one subsection at a time.  For each
subsection,
- check the mundane formatting.  Are the headings (@predefined,
  @seealso, etc) in the right order?
- add any appropriate index entries.
- check the links in the @seealso section -- links to music
  glossary, internal references, and other NR sections are the
  main concern.  Check for potential additions.
- move LSR-worthy material into LSR.  Add the snippet (or
  just send it to Valentin for adding), delete the material from
  the .itely file, and add a @lilypondfile command.

- check the examples and descriptions.  Do they still work?
  *Do not* assume that the existing text is accurate/complete;
  some of the manual is highly out of date.
- is the material in the @knownissues  still accurate?
- process anything on the TODO list on the GDP web site.
- can the examples be improved (made more explanatory), or is
  there any missing info?  (feel free to ask specific questions
  on -user; a couple of people claimed to be interesting in being
  "consultants" who would help with such questions)

In general, I favor short text explanations with good examples --
"an example is worth a thousand words".  When I worked on the
docs, I spent about half my time just working on those tiny
lilypond examples.  Making easily-understandable examples is much
harder than it looks.


TWEAKS

In general, any \set or \override commands should go in the
"select snippets" section, which means that they should go in LSR
and not the .itely file.  For some cases, the command obviously
belongs in the "main text" (ie not inside @predefined or @seealso
or whatever) -- instrument names are a good example of this.
  \set Staff.instrumentName = #"foo"
On the other side of this,
  \override Score.Hairpin #'after-line-breaking = ##t
clearly belongs in LSR.

I'm quite willing to discuss specific cases if you think that a
tweaks needs to be in the main text.  But items that can go into
LSR are easier to maintain, so I'd like to move as much as
possible into there.


It would be "nice" if you spent a lot of time crafting nice tweaks
for users... but my recommendation is *not* to do this.  There's a
lot of doc work to do without adding examples of tweaks.  Tweak
examples are trivial to add later -- they could be made by normal
users, or by you after GDP is over.

Basically, it's not something that needs to be done while I'm
around.  Remember that I'm gone in August at the latest; there's a
*lot* of doc work that should be done before then.  I strongly
recommend that you save all the tweaks until later.


FINAL

- when you think you're finished, let me know.  I'll spend a few
  minutes and send you a list of mistakes to fix.
  (there's a *lot* of details to cover; we'll probably spend a
  week going back and forth like this.  See earlier warning about
  hating me by the time you're done with a doc section :)
- I'll ask people on -user to review the Snippet list at this
  time; correcting things on the Snippet list is much easier than
  getting comments on the integrated snippets.
- when we're both satisfied with the section, we'll invite
  comments from -user.  Judging from my experience with Pitches,
  it will take between three and five weeks to keep on revising
  the "final" version.

I personally found it quite frustrating to still be fixing
problems in a doc section which I thought was "perfect" a whole
bloody *month* ago.  Don't get me wrong; it's great that we get so
many comments from -user.  :)   But just be aware that when you
think you're finally done with a section, you're actually only
halfway there.