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 write:
  49 DYNAMICS may be manually placed above or below the
  50 staff, see @ref{Controlling direction and placement}.
  51
  52 Most tweaks should be added to LSR and not placed directly in the
  53 .itely file.  In some cases, tweaks may be placed in the main
  54 text, but ask about this first.
  55
  56 Finally, you should assume that users know what the notation
  57 means; explaining musical concepts happens in the Music Glossary.
  58
  59
  60 * Application Usage: information about using the program lilypond
  61   with other programs (lilypond-book, operating systems, GUIs,
  62   convert-ly, etc).  This section is written in formal technical
  63   writing style.
  64
  65 Users are not expected to read this manual from start to finish.
  66
  67
  68 * Music Glossary: information about the music notation itself.
  69   Explainations and translations about notation terms go here.
  70
  71 Users are not expected to read this manual from start to finish.
  72
  73 * Internals Reference: not really a documentation book, since it
  74   is automagically generated from the source, but this is its
  75   name.
  76
  77
  78 %%%%% SECTION ORGANIZATION
  79
  80 The order of headings inside documentation sections should be:
  81
  82 main docs
  83 @predefined
  84 @snippets
  85 @seealso
  86 @knownissues
  87
  88 * You _must_ include a @seealso.  The order of items inside the
  89   @seealso section is
  90
  91     Music Glossary:
  92     @rglos{foo},
  93     @rglos{bar}.
  94
  95     Learning Manual:
  96     @rlearning{baz},
  97     @rlearning{foozle}.
  98
  99     Notation Reference:
 100     @ruser{faazle},
 101     @ruser{boo}.
 102
 103     Application Usage:
 104     @rprogram{blah}.
 105
 106     Installed Files:
 107     @file{path/to/dir/blahz}.
 108
 109     Snippets: @rlsr{section}.
 110
 111     Internals Reference:
 112     @rinternals{fazzle},
 113     @rinternals{booar}.
 114
 115       If there are multiple entries, separate them by commas
 116       but do not include an `and'.
 117
 118       Always end with a period.
 119
 120       Place each link on a new line as above; this makes it much
 121       easier to add or remove links.  In the output, they
 122       appear on a single line.
 123
 124   ("Snippets" is REQUIRED; the others are optional)
 125
 126   Any new concepts or links which require an explanation should go
 127   as a full sentence(s) in the main text.
 128
 129 * To create links, use @ref{} if the link is within the same
 130   manual.
 131
 132 * @predefined  is for commands in ly/property-init.ly
 133
 134 * Do not include any real info in second-level sections (ie 1.1
 135   Pitches).  A first-level section may have introductory material,
 136   but other than that all material goes into third-level sections
 137   (ie 1.1.1 Writing Pitches).
 138
 139
 140 %%%%% GENERAL WRITING
 141
 142 * Do not forget to create @cindex entries for new sections of text.
 143   Enter commands with @funindex, i.e.
 144     @cindex pitches, writing in different octaves
 145     @funindex \relative
 146   do not bother with the @code{} (they are added automatically).  These
 147   items are added to both the command index and the unified index.
 148
 149   Both index commands should go in front of the actual material.
 150
 151   @cindex entries should not be capitalized, ie
 152     @cindex time signature
 153   is preferred.  (instead of `Time signature')   Only use capital
 154   letters for musical terms which demand them, like D.S. al Fine.
 155
 156 * Preferred terms:
 157     - in general, use the American spellings.  The internal
 158       lilypond property names use this spelling.
 159     - list of specific terms:
 160 canceled
 161 simultaenous    NOT concurrent
 162 measure: the unit of music
 163 bar line: the symbol delimiting a measure   NOT barline
 164 note head   NOT notehead
 165 chord construct   NOT chord (when referring to <>)
 166
 167
 168 %%%%% TECHNICAL WRITING STYLE
 169
 170 * Do not refer to LilyPond in the text.  The reader knows what the
 171   manual is about.  If you do, capitalization is LilyPond.
 172
 173 * If you explicitly refer to `lilypond' the program (or any other
 174   command to be executed), say `@command{lilypond}'.
 175
 176 * Do not explicitly refer to the reader/user.  There is no one
 177   else besides the reader and the writer.
 178
 179 * Do not use abbreviations (don't, won't, etc.).  If you do, use a
 180   comma after it:
 181
 182     blabla blabla, i.e., blabla blabla
 183
 184 * Avoid fluff (``Notice that,'' ``as you can see,''
 185   ``Currently,'').
 186
 187 * The use of the word `illegal' is inappropriate in most cases.
 188   Say `invalid' instead.
 189
 190
 191