X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fpolicy.txt;h=329b72427ec6a20f6bbfb894b12b3afebd2a1643;hb=c20a51c975597604f877e01ffdd720b9750ab9b1;hp=262b61d6710d7dd5c8518c51acf401b57b6c93be;hpb=8713c7b90c7f56171fa92ac322acca08de5dcce0;p=lilypond.git

diff --git a/Documentation/user/policy.txt b/Documentation/user/policy.txt
index 262b61d671..329b72427e 100644
--- a/Documentation/user/policy.txt
+++ b/Documentation/user/policy.txt
@@ -8,11 +8,22 @@ 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.
+* Learning Manual:
+  The LM is written in a tutorial style which introduces the most
+  important concepts, structure and syntax of the elements of a
+  LilyPond score in a carefully graded sequence of steps.
+  Explanations of all musical concepts used in the Manual can be
+  found in the Music Glossary, and readers are assumed to have no
+  prior knowledge of LilyPond.  The objective is to take readers to
+  a level where the Notation Reference can be understood and
+  employed to both adapt the templates in the Appendix to their
+  needs and to begin to construct their own scores.  Commonly used
+  tweaks are introduced and explained.  Examples are provided
+  throughout which, while being focussed on the topic being
+  introduced, are long enough to seem real in order to retain the
+  readers' interest.  Each example builds on the previous material,
+  and comments are used liberally.  Every new aspect is thoroughly
+  explained before it is used.
 
 Users are encouraged to read the complete Learning Manual from
 start-to-finish.
@@ -68,7 +79,7 @@ main docs
 * You _must_ include a @seealso.  The order of items inside the
   @seealso section is
 
-    Music glossary: @rglos{foo}, @rglos{bar}.
+    Music Glossary: @rglos{foo}, @rglos{bar}.
 
     Learning Manual: @rlearning{baz}, @rlearning{foozle}
 
@@ -76,7 +87,7 @@ main docs
 
     Application Usage: @rprogram{blah}.
 
-    Installed files: @file{path/to/dir/blahz}.
+    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
@@ -87,6 +98,9 @@ main docs
 
   ("Snippets" is REQUIRED; the others are optional)
 
+  Any new concepts or links which require an explanation should go
+  as a full sentence(s) in the main text.
+
 * To create links, use @ref{} if the link is within the same
   manual.
 
@@ -107,11 +121,17 @@ main docs
 
   Both index commands should go in front of the actual material.
 
+  @cindex should not be capitalized.
+
 * Preferred terms:
     - in general, use the American spellings.  The internal
       lilypond property names use this spelling.
     - list of specific terms:
-canceled, 
+canceled
+simultaenous    NOT concurrent
+measure: the unit of music
+bar line: the symbol delimiting a measure
+
 
 
 %%%%% TECHNICAL WRITING STYLE