DOCUMENTATION POLICY
--------------------


%%%%% BOOKS

There are four parts to the documentation: the Learning Manual,
the Notation Reference, the Program Reference, and the Music
Glossary.

* Learning Manual: long, chatty, friendly explanations go here.
  This is aimed at users learning something for the first time --
  not necessarily just learning lilypond notation, but also things
  like learning how to deal with projects, tweaking, preparing parts
  for orchestras, etc.  Less formal language may be used here.

Users are encouraged to read the complete Learning Manual from
start-to-finish.


* Notation Reference: a (hopefully complete) description of
  LilyPond input notation.  Some material from here may be
  duplicated in the Learning Manual (for teaching).  The material is
  presented in an approximate order of increasing difficulty, but
  the goal is _not_ to provide a step-by-step learning environment.
  For example, all material under "Pitches" should remain in that
  section, even though microtonal accidentals may seem more advanced
  than info about clefs or time signatures -- "Pitches" should be a
  one-stop reference about the pitch portion of notes.  This section
  is written in formal technical writing style.

Users are not expected to read this manual from start to finish.
However, they should be familiar with the material in the Learning
Manual (particularly ``Fundamental Concepts''), so do not repeat
that material in this book.  Also, you should assume that users
know what the notation means; explaining musical concepts happens
in the Music Glossary.


* Application Usage: information about using the program lilypond
  with other programs (lilypond-book, operating systems, GUIs,
  convert-ly, etc).  This section is written in formal technical
  writing style.

Users are not expected to read this manual from start to finish.


* Music Glossary: information about the music notation itself.
  Explainations and translations about notation terms go here.

Users are not expected to read this manual from start to finish.

* Internals Reference: not really a documentation book, since it
  is automagically generated from the source, but this is its
  name.


%%%%% SECTION ORGANIZATION

The order of headings inside documentation sections should be:

main docs
@refcommands
@commonprop
@seealso
@refbugs

* You _must_ include a @seealso.  The order of items inside the
  @seealso section is

    Music glossary: @rglos{foo}, @rglos{bar}.

    Learning Manual: @rlearning{baz}, @rlearning{foozle}

    Notation Reference: @ruser{faazle}, @ruser{boo}.

    Application Usage: @rprogram{blah}.

    Installed files: @file{path/to/dir/blahz}.

    Snippets: @lsrdir{section}, @lsr{specific/example-name.ly}.
      (if there is only one entry, omit a final period.  If there
       are multiple entries, separate them by commas, do not
       include an `and', and end with a period.)

    Internals Reference: @internalsref{fazzle}, @internalsref{booar}.

  ("Snippets" is REQUIRED; the others are optional)

* To create links, use @ref{} if the link is within the same
  manual.

* Do not include any real info in second-level sections (ie 1.1
  Pitches).  A first-level section may have introductory material,
  but other than that all material goes into third-level sections
  (ie 1.1.1 Writing Pitches).


%%%%% GENERAL WRITING

* Do not forget to create @cindex entries for new sections of text.
  Enter commands with @funindex, i.e.
    @cindex pitches, writing in different octaves
    @funindex \relative
  do not bother with the @code{} (they are added automatically).  These
  items are added to both the command index and the unified index.

  Both index commands should go in front of the actual material.

* Preferred terms:
    - in general, use the American spellings.  The internal
      lilypond property names use this spelling.
    - list of specific terms:
canceled, 


%%%%% TECHNICAL WRITING STYLE

* Do not refer to LilyPond in the text.  The reader knows what the
  manual is about.  If you do, capitalization is LilyPond.

* If you explicitly refer to `lilypond' the program (or any other
  command to be executed), say `@command{lilypond}'.

* Do not explicitly refer to the reader/user.  There is no one
  else besides the reader and the writer.

* Do not use abbreviations (don't, won't, etc.).  If you do, use a
  comma after it:

    blabla blabla, i.e., blabla blabla

* Avoid fluff (``Notice that,'' ``as you can see,''
  ``Currently,'').

* The use of the word `illegal' is inappropriate in most cases.
  Say `invalid' instead.