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).  The material is
  35   presented in an approximate order of increasing difficulty, but
  36   the goal is _not_ to provide a step-by-step learning environment.
  37   For example, all material under "Pitches" should remain in that
  38   section, even though microtonal accidentals may seem more advanced
  39   than info about clefs or time signatures -- "Pitches" should be a
  40   one-stop reference about the pitch portion of notes.  This section
  41   is written in formal technical writing style.
  42
  43 Users are not expected to read this manual from start to finish.
  44 However, they should be familiar with the material in the Learning
  45 Manual (particularly ``Fundamental Concepts''), so do not repeat
  46 that material in each section of this book.  Also, you should
  47 assume that users know what the notation means; explaining musical
  48 concepts happens in the Music Glossary.
  49
  50
  51 * Application Usage: information about using the program lilypond
  52   with other programs (lilypond-book, operating systems, GUIs,
  53   convert-ly, etc).  This section is written in formal technical
  54   writing style.
  55
  56 Users are not expected to read this manual from start to finish.
  57
  58
  59 * Music Glossary: information about the music notation itself.
  60   Explainations and translations about notation terms go here.
  61
  62 Users are not expected to read this manual from start to finish.
  63
  64 * Internals Reference: not really a documentation book, since it
  65   is automagically generated from the source, but this is its
  66   name.
  67
  68
  69 %%%%% SECTION ORGANIZATION
  70
  71 The order of headings inside documentation sections should be:
  72
  73 main docs
  74 @refcommands
  75 @commonprop
  76 @seealso
  77 @refbugs
  78
  79 * You _must_ include a @seealso.  The order of items inside the
  80   @seealso section is
  81
  82     Music Glossary: @rglos{foo}, @rglos{bar}.
  83
  84     Learning Manual: @rlearning{baz}, @rlearning{foozle}
  85
  86     Notation Reference: @ruser{faazle}, @ruser{boo}.
  87
  88     Application Usage: @rprogram{blah}.
  89
  90     Installed Files: @file{path/to/dir/blahz}.
  91
  92     Snippets: @lsrdir{section}, @lsr{specific/example-name.ly}.
  93       (if there is only one entry, omit a final period.  If there
  94        are multiple entries, separate them by commas, do not
  95        include an `and', and end with a period.)
  96
  97     Internals Reference: @internalsref{fazzle}, @internalsref{booar}.
  98
  99   ("Snippets" is REQUIRED; the others are optional)
 100
 101   Any new concepts or links which require an explanation should go
 102   as a full sentence(s) in the main text.
 103
 104 * To create links, use @ref{} if the link is within the same
 105   manual.
 106
 107 * Do not include any real info in second-level sections (ie 1.1
 108   Pitches).  A first-level section may have introductory material,
 109   but other than that all material goes into third-level sections
 110   (ie 1.1.1 Writing Pitches).
 111
 112
 113 %%%%% GENERAL WRITING
 114
 115 * Do not forget to create @cindex entries for new sections of text.
 116   Enter commands with @funindex, i.e.
 117     @cindex pitches, writing in different octaves
 118     @funindex \relative
 119   do not bother with the @code{} (they are added automatically).  These
 120   items are added to both the command index and the unified index.
 121
 122   Both index commands should go in front of the actual material.
 123
 124   @cindex entries should not be capitalized, ie
 125     @cindex time signature
 126   is preferred.  (instead of `Time signature')   Only use capital
 127   letters for musical terms which demand them, like D.S. al Fine.
 128
 129 * Preferred terms:
 130     - in general, use the American spellings.  The internal
 131       lilypond property names use this spelling.
 132     - list of specific terms:
 133 canceled
 134 simultaenous    NOT concurrent
 135 measure: the unit of music
 136 bar line: the symbol delimiting a measure   NOT barline
 137 note head   NOT notehead
 138
 139
 140 %%%%% TECHNICAL WRITING STYLE
 141
 142 * Do not refer to LilyPond in the text.  The reader knows what the
 143   manual is about.  If you do, capitalization is LilyPond.
 144
 145 * If you explicitly refer to `lilypond' the program (or any other
 146   command to be executed), say `@command{lilypond}'.
 147
 148 * Do not explicitly refer to the reader/user.  There is no one
 149   else besides the reader and the writer.
 150
 151 * Do not use abbreviations (don't, won't, etc.).  If you do, use a
 152   comma after it:
 153
 154     blabla blabla, i.e., blabla blabla
 155
 156 * Avoid fluff (``Notice that,'' ``as you can see,''
 157   ``Currently,'').
 158
 159 * The use of the word `illegal' is inappropriate in most cases.
 160   Say `invalid' instead.
 161
 162
 163