GDP: documentation guidelines

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

GDP: documentation guidelines

Graham Percival-2
I've updated the README.txt with more guidelines about
writing/maintaining documentation.  I'll be asking the GDP Helpers to
fix any Section organiztion and Formatting issues, as well as any
Readability or Technical writing issues they feel comfortable updating.

If I've forgotten anything from this list, please speak up so we can add
them now.



Info for Documentation
----------------------

%%%%% UPDATING DOCS
convert-ly -e --from=... --to=... --no-version *.itely

% to find the current version number,
grep "version \"" tutorial.itely

%  (nobody ever remembers to update this file, so I've stopped
%  trying to record it here)


%%%%% BOOKS

There are three parts to the documentation: the Learning Manual,
the Notation Reference, and the Technical Details.

* 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.


* Program 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.


%%%%% SECTION ORGANIZATION

The order of headings inside documentation sections should be:

main docs
@refcommands
@commonprop
@seealso
@refbugs

(omit any headings which do not apply)

Including at least one link to @lsrdir{} inside @seealso is
highly recommended.


%%%%% FORMATTING

* Use two spaces for indentation in lilypond examples.

* Do not use tabs.  They expand to nothing in DVI output.

* Do not use spaces at the beginning of a line (except in @example
   or @verbatim environments), and do not use more than a single
   space between words.  `makeinfo' copies the input lines verbatim
   without removing those spaces.

* Use two spaces after a period.

* Don't use a @ref{link to another section} in the middle of a
   sentence.  It looks ok in HTML, moderately bad in PDF, and
   utterly horrible in INFO.  Instead, reword the sentence so that
   users are encouraged to see @ref{link to another section}.
   (at the end of the sentence)

* Variables or numbers which consist of a single character
   (probably followed by a punctuation mark) should be tied
   properly, either to the previous or the next word.  Example:

       The variable@tie{}@var{a} ...

* To get consistent indentation in the DVI output it is better to
   avoid the @verbatim environment.  Use the @example environment
   instead if possible, but without extraneous indentation.  For
   example, this

     @example
       foo {
         bar
       }
     @end example

   should be replaced with

     @example
     foo {
       bar
     }
     @end example

   where `@example' starts the line (without leading spaces).

* Use the `quote' option in @lilypond commands if possible.

   Do not compress the input vertically; this is, do not use

     Beginning of logical unit
     @example
     ...
     @end example
     continuation of logical unit

   but

     Beginning of logical unit

     @example
     ...
     @end example

     @noindent
     continuation of logical unit

   This makes it easier to avoid forgetting the `@noindent'.

* Non-ASCII characters which are in utf-8 should be directly used;
   this is, don't say `Ba@ss{}tuba' but `Baßtuba'.  This ensures that
   all such characters appear in all output formats.

* Lines should be less than 72 characters long.  (I personally
   recommend writing with 66-char lines, but don't bother modifying
   existing material.)

* Use @q instead of `...' and @qq instead of ``...''.  The latter macro
   should be used with care since we use `...' as the default quoting
   throughout the manual, except for things related to direct speech.

   Warning: @q{} and @qq{} *MUST NOT* come at the end or beginning
   of a line (unless it begins the paragraph).  If these macros
   @qq{appear like this}, then they will being a new paragraph.

   In most cases, you should use @code{} or @samp{} instead.


%%%%% READIBILITY

* LilyPond input should be produce via
     @lilypond[verbatim,quote,ragged-right]
   with `fragment' and `relative=2' optional.

   Examples about page layout may alter the quote/ragged-right
   options.  Omitting `verbatim' is not recommended (other than the
   ``inspirational headword'' examples)

* 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.

* Avoid long stretches of input code.  Noone is going to read them in
   print.  Instead refer to an example input file (with @lsr{}); these
   are clickable in HTML.

* Abbrevs in caps, e.g., HTML, DVI, MIDI, etc.

* Colon usage

   1. To introduce lists
   2. When beginning a quote: "So, he said,..."
      This usage is rarer.  Americans often just use a comma.
   3. When adding a defining example at the end of a sentence.


%%%%% HINTS FOR 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.





_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: GDP: documentation guidelines

Juergen Reuter
On Fri, 21 Sep 2007, Graham Percival wrote:

> I've updated the README.txt with more guidelines about writing/maintaining
> documentation.  I'll be asking the GDP Helpers to fix any Section organiztion
> and Formatting issues, as well as any Readability or Technical writing issues
> they feel comfortable updating.
>
> If I've forgotten anything from this list, please speak up so we can add them
> now.
>

I would expect the contents of README.txt to be part of the online
documentation and therefore available at:
http://lilypond.org/doc/v2.10/Documentation/user/README
However, obviously this file is not generated from README.txt or at least
not put into the documentation out directory.  Or is it available under
some different URL?

I also strongly suggest to put a link to this resource on some prominent
page, maybe on:
http://lilypond.org/web/devel/participating/
Otherwise, I think this file is too well hidden to be found by occasional
documentation writers.

Greetings,
Juergen


_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: GDP: documentation guidelines

John Mandereau-2
Le dimanche 23 septembre 2007 à 16:38 +0200, Juergen Reuter a écrit :
> I would expect the contents of README.txt to be part of the online
> documentation and therefore available at:
> http://lilypond.org/doc/v2.10/Documentation/user/README
> However, obviously this file is not generated from README.txt or at least
> not put into the documentation out directory.  Or is it available under
> some different URL?

There's no need to add README.txt to the compiled docs, as we can
directly refer to the sources:
http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=blob_plain;f=Documentation/user/README.txt;hb=lilypond/gdp

where f is generally the file path and hb is the branch name.


> I also strongly suggest to put a link to this resource on some prominent
> page, maybe on:
> http://lilypond.org/web/devel/participating/
> Otherwise, I think this file is too well hidden to be found by occasional
> documentation writers.

Why not adding it on documentation-adding and "Developers
resources" (linked from Documentation index)?

Cheers,
John



_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: GDP: documentation guidelines

Graham Percival-2
John Mandereau wrote:
> There's no need to add README.txt to the compiled docs, as we can
> directly refer to the sources:
> http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=blob_plain;f=Documentation/user/README.txt;hb=lilypond/gdp
>
> Why not adding it on documentation-adding and "Developers
> resources" (linked from Documentation index)?

Sounds good.  Could you add this to your list, John?  We only need to
link to the GDP branch until 2.13 exists (and we merge GDP); thereafter
it should point to master.

Sorry to add more stuff to you,
- Graham


_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: GDP: documentation guidelines

John Mandereau-2
Le vendredi 28 septembre 2007 à 20:15 -0700, Graham Percival a écrit :

> John Mandereau wrote:
> > There's no need to add README.txt to the compiled docs, as we can
> > directly refer to the sources:
> > http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=blob_plain;f=Documentation/user/README.txt;hb=lilypond/gdp
> >
> > Why not adding it on documentation-adding and "Developers
> > resources" (linked from Documentation index)?
>
> Sounds good.  Could you add this to your list, John?  We only need to
> link to the GDP branch until 2.13 exists (and we merge GDP); thereafter
> it should point to master.

Done.  I also added blurb in documentation-adding, please fix if needed.

Cheers,
John



_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel