Documentation/user/writing-sections.txt

   1 CHECKLIST FOR DOC SECTION REWRITES
   2
   3 You've volunteered (or are considering volunteering) to edit a
   4 section of the NR.  Congratulations!  You'll learn a lot about
   5 this part of lilypond.  You'll also get thoroughly fed up with
   6 documentation work, and especially with me... but as they say,
   7 "you can't make an omelett without breaking a few eggs".  Welcome
   8 to egg-hood!
   9
  10 REQUIRED READING
  11
  12 - policy.txt
  13 - writing-texinfo.txt
  14 - this document :)
  15 - NR 1.1 Pitches.  Ideally, read it in your favorite output format
  16   (either info, PDF, or HTML), *and* in source format
  17   (pitches.itely).  This is our "demonstration" chapter, so the
  18   below points really just boil down to "make it like
  19   pitches.itely".
  20
  21
  22 WORKING
  23
  24 I recommend working on one subsection at a time.  For each
  25 subsection,
  26 - check the mundane formatting.  Are the headings (@predefined,
  27   @seealso, etc) in the right order?
  28 - add any appropriate index entries.
  29 - check the links in the @seealso section -- links to music
  30   glossary, internal references, and other NR sections are the
  31   main concern.  Check for potential additions.
  32 - move LSR-worthy material into LSR.  Add the snippet (or
  33   just send it to Valentin for adding), delete the material from
  34   the .itely file, and add a @lilypondfile command.
  35
  36 - check the examples and descriptions.  Do they still work?
  37   *Do not* assume that the existing text is accurate/complete;
  38   some of the manual is highly out of date.
  39 - is the material in the @knownissues  still accurate?
  40 - process anything on the TODO list on the GDP web site.
  41 - can the examples be improved (made more explanatory), or is
  42   there any missing info?  (feel free to ask specific questions
  43   on -user; a couple of people claimed to be interesting in being
  44   "consultants" who would help with such questions)
  45
  46 In general, I favor short text explanations with good examples --
  47 "an example is worth a thousand words".  When I worked on the
  48 docs, I spent about half my time just working on those tiny
  49 lilypond examples.  Making easily-understandable examples is much
  50 harder than it looks.
  51
  52
  53 TWEAKS
  54
  55 In general, any \set or \override commands should go in the
  56 "select snippets" section, which means that they should go in LSR
  57 and not the .itely file.  For some cases, the command obviously
  58 belongs in the "main text" (ie not inside @predefined or @seealso
  59 or whatever) -- instrument names are a good example of this.
  60   \set Staff.instrumentName = #"foo"
  61 On the other side of this,
  62   \override Score.Hairpin #'after-line-breaking = ##t
  63 clearly belongs in LSR.
  64
  65 I'm quite willing to discuss specific cases if you think that a
  66 tweaks needs to be in the main text.  But items that can go into
  67 LSR are easier to maintain, so I'd like to move as much as
  68 possible into there.
  69
  70
  71 It would be "nice" if you spent a lot of time crafting nice tweaks
  72 for users... but my recommendation is *not* to do this.  There's a
  73 lot of doc work to do without adding examples of tweaks.  Tweak
  74 examples are trivial to add later -- they could be made by normal
  75 users, or by you after GDP is over.
  76
  77 Basically, it's not something that needs to be done while I'm
  78 around.  Remember that I'm gone in August at the latest; there's a
  79 *lot* of doc work that should be done before then.  I strongly
  80 recommend that you save all the tweaks until later.
  81
  82
  83 FINAL
  84
  85 - when you think you're finished, let me know.  I'll spend a few
  86   minutes and send you a list of mistakes to fix.
  87   (there's a *lot* of details to cover; we'll probably spend a
  88   week going back and forth like this.  See earlier warning about
  89   hating me by the time you're done with a doc section :)
  90 - I'll ask people on -user to review the Snippet list at this
  91   time; correcting things on the Snippet list is much easier than
  92   getting comments on the integrated snippets.
  93 - when we're both satisfied with the section, we'll invite
  94   comments from -user.  Judging from my experience with Pitches,
  95   it will take between three and five weeks to keep on revising
  96   the "final" version.
  97
  98 I personally found it quite frustrating to still be fixing
  99 problems in a doc section which I thought was "perfect" a whole
 100 bloody *month* ago.  Don't get me wrong; it's great that we get so
 101 many comments from -user.  :)   But just be aware that when you
 102 think you're finally done with a section, you're actually only
 103 halfway there.
 104
 105
 106