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