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 (or whatever) may be manually placed above or below the
  50 staff, for details 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: @rglos{foo}, @rglos{bar}.
  92
  93     Learning Manual: @rlearning{baz}, @rlearning{foozle}
  94
  95     Notation Reference: @ruser{faazle}, @ruser{boo}.
  96
  97     Application Usage: @rprogram{blah}.
  98
  99     Installed Files: @file{path/to/dir/blahz}.
 100
 101     Snippets: @lsrdir{section}, @lsr{specific/example-name.ly}.
 102       (if there is only one entry, omit a final period.  If there
 103        are multiple entries, separate them by commas, do not
 104        include an `and', and end with a period.)
 105
 106     Internals Reference: @internalsref{fazzle}, @internalsref{booar}.
 107
 108   ("Snippets" is REQUIRED; the others are optional)
 109
 110   Any new concepts or links which require an explanation should go
 111   as a full sentence(s) in the main text.
 112
 113 * To create links, use @ref{} if the link is within the same
 114   manual.
 115
 116 * Do not include any real info in second-level sections (ie 1.1
 117   Pitches).  A first-level section may have introductory material,
 118   but other than that all material goes into third-level sections
 119   (ie 1.1.1 Writing Pitches).
 120
 121
 122 %%%%% GENERAL WRITING
 123
 124 * Do not forget to create @cindex entries for new sections of text.
 125   Enter commands with @funindex, i.e.
 126     @cindex pitches, writing in different octaves
 127     @funindex \relative
 128   do not bother with the @code{} (they are added automatically).  These
 129   items are added to both the command index and the unified index.
 130
 131   Both index commands should go in front of the actual material.
 132
 133   @cindex entries should not be capitalized, ie
 134     @cindex time signature
 135   is preferred.  (instead of `Time signature')   Only use capital
 136   letters for musical terms which demand them, like D.S. al Fine.
 137
 138 * Preferred terms:
 139     - in general, use the American spellings.  The internal
 140       lilypond property names use this spelling.
 141     - list of specific terms:
 142 canceled
 143 simultaenous    NOT concurrent
 144 measure: the unit of music
 145 bar line: the symbol delimiting a measure   NOT barline
 146 note head   NOT notehead
 147
 148
 149 %%%%% TECHNICAL WRITING STYLE
 150
 151 * Do not refer to LilyPond in the text.  The reader knows what the
 152   manual is about.  If you do, capitalization is LilyPond.
 153
 154 * If you explicitly refer to `lilypond' the program (or any other
 155   command to be executed), say `@command{lilypond}'.
 156
 157 * Do not explicitly refer to the reader/user.  There is no one
 158   else besides the reader and the writer.
 159
 160 * Do not use abbreviations (don't, won't, etc.).  If you do, use a
 161   comma after it:
 162
 163     blabla blabla, i.e., blabla blabla
 164
 165 * Avoid fluff (``Notice that,'' ``as you can see,''
 166   ``Currently,'').
 167
 168 * The use of the word `illegal' is inappropriate in most cases.
 169   Say `invalid' instead.
 170
 171
 172