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 _______________________________________________ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
