Re: GDP: chattiness in @seealso

[David Fedoruk]

Good questions!
>
> (another overdue discussion question, sorry)

IMHO this isn't a problem. The crucial thing to remember is that
program documentation isn't for programmers (they have comments in the
working code), its for us non-programmers who struggle with programs
like lilypond because it requires us to learn to think differently
about notes and music than we are used to.

Full sentences in the language of the documentation is preferable. A
full sentence engages, or draws the reader into the program in a way
that the terseness of choice 1 or 3 cannot do. It can also prevent the
reader from ducking into blind alleys. This prevents much head banging
(less risk of permanent damage to) and general frustration.

Links and "see also" references are good ways to redirect someone who
is not quite sure where to look for what they are looking for. Many
times I have a question which I do not know the correct words for. I
guess at how the question might be worded. I am right about 50 percent
of the time. When I am not right, those see also references usually
are the ones that save me from much head banging.

I have (on occasion) actually sat in a chair away from the computer
and read computer documentation. I don't believe documentation is
simply on-the-fly reading. It should be a well thought out description
with instruction on how to use the program it accompanies. It is a
literary work of its own. The skill and craft of it is to be on point;
engaging and readable all at the same time.

What I am saying is that presentation matters. It is essentially first
contact for newbies using lilypond. The longer you use lilypond, the
less you depend on documentation. The speed with which that happens is
in large part due to the skill with which the documentation is
written. Without a doubt, number 2 is the best option.

I had not intended to use so many words, but this sums up my thoughts
on documentation and specifically on this question.

>
> Take a look at the "see also" sections in
>         NR 1.1.3 Displaying pitches: Instrument transpositions
> and
>         NR 1.2.1 Writing rhythms: Durations
>
> In 1.1.3, we have a short, compact format:
> ----
> Notation reference: Quoting other voices, Transpose.
> ----
>
> In 1.2.1, there's much more explanation of why people might want to look
> at each link:
> ----
> For ways of specifying durations for the syllables of lyrics and ways of
> aligning lyrics to notes see Vocal music.
>
> For a description of how to enter rests see Writing rests.
>
> A note with the duration of a quadruple breve may be entered with
> \maxima, but this is supported only within ancient music notation; see
> Ancient notation.
>
> Optionally, notes can be spaced proportionately to their duration. For
> details of this and other settings which control proportional notation
> see Proportional notation.

I have often found the footnotes in a book or article as interesting
or more interesting than the main piece of writing.


Cheers,
David


--
David Fedoruk
B.Mus. UBC,1986
Certificate in Internet Systems Administration, UBC, 2003


http://recordjackethistorian.wordpress.com
"Music is enough for one's life time, but one life time is not enough
for music" Sergei Rachmaninov