Documentation/user/policy.txt

   1 DOCUMENTATION POLICY
   2 --------------------
   3
   4
   5 %%%%% BOOKS
   6
   7 There are four parts to the documentation: the Learning Manual,
   8 the Notation Reference, the Program Reference, and the Music
   9 Glossary.
  10
  11 * Learning Manual:
  12   The LM is written in a tutorial style which introduces the most
  13   important concepts, structure and syntax of the elements of a
  14   LilyPond score in a carefully graded sequence of steps.
  15   Explanations of all musical concepts used in the Manual can be
  16   found in the Music Glossary, and readers are assumed to have no
  17   prior knowledge of LilyPond.  The objective is to take readers to
  18   a level where the Notation Reference can be understood and
  19   employed to both adapt the templates in the Appendix to their
  20   needs and to begin to construct their own scores.  Commonly used
  21   tweaks are introduced and explained.  Examples are provided
  22   throughout which, while being focussed on the topic being
  23   introduced, are long enough to seem real in order to retain the
  24   readers' interest.  Each example builds on the previous material,
  25   and comments are used liberally.  Every new aspect is thoroughly
  26   explained before it is used.
  27
  28 Users are encouraged to read the complete Learning Manual from
  29 start-to-finish.
  30
  31
  32 * Notation Reference: a (hopefully complete) description of
  33   LilyPond input notation.  Some material from here may be
  34   duplicated in the Learning Manual (for teaching), but consider
  35   the NR to be the "definitive" description of each notation
  36   element, with the LM being an "extra".  The goal is _not_ to
  37   provide a step-by-step learning environment -- do not avoid
  38   using notation that has not be introduced previously in the
  39   NR  (for example, use \break if appropriate).  This section is
  40   written in formal technical writing style.
  41
  42 Avoid duplication.  Although users are not expected to read this
  43 manual from start to finish, they should be familiar with the
  44 material in the Learning Manual (particularly ``Fundamental
  45 Concepts''), so do not repeat that material in each section of
  46 this book.  Also watch out for common constructs, like ^ - _ for
  47 directions -- those are explained in NR 3.  In NR 1, you can
  48 mention that "dynamics (or whatever) may be placed above or below
  49 the staff, for details see @ref{Up and down}".
  50
  51 Most tweaks should be added to LSR and not placed directly in the
  52 .itely file.  In some cases, tweaks may be placed in the main
  53 text, but ask about this first.
  54
  55 Finally, you should assume that users know what the notation
  56 means; explaining musical concepts happens in the Music Glossary.
  57
  58
  59 * Application Usage: information about using the program lilypond
  60   with other programs (lilypond-book, operating systems, GUIs,
  61   convert-ly, etc).  This section is written in formal technical
  62   writing style.
  63
  64 Users are not expected to read this manual from start to finish.
  65
  66
  67 * Music Glossary: information about the music notation itself.
  68   Explainations and translations about notation terms go here.
  69
  70 Users are not expected to read this manual from start to finish.
  71
  72 * Internals Reference: not really a documentation book, since it
  73   is automagically generated from the source, but this is its
  74   name.
  75
  76
  77 %%%%% SECTION ORGANIZATION
  78
  79 The order of headings inside documentation sections should be:
  80
  81 main docs
  82 @refcommands
  83 @commonprop
  84 @seealso
  85 @refbugs
  86
  87 * You _must_ include a @seealso.  The order of items inside the
  88   @seealso section is
  89
  90     Music Glossary: @rglos{foo}, @rglos{bar}.
  91
  92     Learning Manual: @rlearning{baz}, @rlearning{foozle}
  93
  94     Notation Reference: @ruser{faazle}, @ruser{boo}.
  95
  96     Application Usage: @rprogram{blah}.
  97
  98     Installed Files: @file{path/to/dir/blahz}.
  99
 100     Snippets: @lsrdir{section}, @lsr{specific/example-name.ly}.
 101       (if there is only one entry, omit a final period.  If there
 102        are multiple entries, separate them by commas, do not
 103        include an `and', and end with a period.)
 104
 105     Internals Reference: @internalsref{fazzle}, @internalsref{booar}.
 106
 107   ("Snippets" is REQUIRED; the others are optional)
 108
 109   Any new concepts or links which require an explanation should go
 110   as a full sentence(s) in the main text.
 111
 112 * To create links, use @ref{} if the link is within the same
 113   manual.
 114
 115 * Do not include any real info in second-level sections (ie 1.1
 116   Pitches).  A first-level section may have introductory material,
 117   but other than that all material goes into third-level sections
 118   (ie 1.1.1 Writing Pitches).
 119
 120
 121 %%%%% GENERAL WRITING
 122
 123 * Do not forget to create @cindex entries for new sections of text.
 124   Enter commands with @funindex, i.e.
 125     @cindex pitches, writing in different octaves
 126     @funindex \relative
 127   do not bother with the @code{} (they are added automatically).  These
 128   items are added to both the command index and the unified index.
 129
 130   Both index commands should go in front of the actual material.
 131
 132   @cindex entries should not be capitalized, ie
 133     @cindex time signature
 134   is preferred.  (instead of `Time signature')   Only use capital
 135   letters for musical terms which demand them, like D.S. al Fine.
 136
 137 * Preferred terms:
 138     - in general, use the American spellings.  The internal
 139       lilypond property names use this spelling.
 140     - list of specific terms:
 141 canceled
 142 simultaenous    NOT concurrent
 143 measure: the unit of music
 144 bar line: the symbol delimiting a measure   NOT barline
 145 note head   NOT notehead
 146
 147
 148 %%%%% TECHNICAL WRITING STYLE
 149
 150 * Do not refer to LilyPond in the text.  The reader knows what the
 151   manual is about.  If you do, capitalization is LilyPond.
 152
 153 * If you explicitly refer to `lilypond' the program (or any other
 154   command to be executed), say `@command{lilypond}'.
 155
 156 * Do not explicitly refer to the reader/user.  There is no one
 157   else besides the reader and the writer.
 158
 159 * Do not use abbreviations (don't, won't, etc.).  If you do, use a
 160   comma after it:
 161
 162     blabla blabla, i.e., blabla blabla
 163
 164 * Avoid fluff (``Notice that,'' ``as you can see,''
 165   ``Currently,'').
 166
 167 * The use of the word `illegal' is inappropriate in most cases.
 168   Say `invalid' instead.
 169
 170
 171