Re: GDP: chattiness in @seealso
Mats Bengtsson wrote:
I'm not sure what the conclusion is, but maybe we can reformulate the
original question into:
- Should we introduce some new concepts under @seealso or should this
always be done in the main text?
Let's go with "main text". I'm not completely dead-set on this option,
but I don't think anybody is going to seriously argue against it.
- For issues that are somewhat peripheral and just need a short intro and a
cross reference, should they be described in running text or in an item
list?
The problem with an item list is that it raises questions about anything
which is _not_ on the list. For example, @ref{Ties} doesn't appear in
the item list in Durations. And if we move all the explanations away
from the @seealso, it would seem really weird to include @ref{Ties} in
the main text, then again in an item list in the main text, then _again_
in the complete reference list in @seealso.
So right now my vote is to describe anything which needs describing in
the main text.
- Under @seealso, can we find a nice layout that allows for a mix of
pure links
which already have self-explanatory names, with links that need a
sentence of
explanation?
I can't think of any /nice/ layout. A list that alternates
full-sentences and single-word references is going to look weird. A
typical comma-separated horizontal list would still look slightly
awkward even with the parenthetical remarks.
With all that in mind, I'm proposing that we move all sentences into the
main text, and have a simple
@seealso
Notation Reference: @ref{foo}, @ref{bar}.
- Is there a need to repeat all links from the main text also in @seealso?
Perhaps not a need, but I feel a strong desire to do so. It's a simple
enough job for the Formatters.
A side comment: in "Durations" under @refbugs, the term "glyphs"
is used several times. Is this is term that is well-known to all
readers, or
is it only known to hackers?
I deliberately decided not to spend time agonizing over this. I just
dumped Han-Wen's email in that section. As a general rule, the @refbugs
will be more technical, harder to understand, and may possibly be a
simple copy&paste from a hacker's email or bug respose.
Making @refbugs easier to read might be something to schedule in the
third round of GDP, but certainly not before that. (first round: making
GDP presentable again. Second round: making GDP significantly better
than 2.11 in all respects. Third round: perfection)
Cheers,
- Graham
___
lilypond-user mailing list
lilypond-user@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: chattiness in @seealso
Graham Percival wrote:
At the very least, I want it clear which sentence refer to the
Notation Reference, and which sentences refer to the other parts of
the docs.
... I _really_ think this is completely unnecessary, though. And if
you want to add full sentences to every single notation reference
@ref{}, I assume you want to do the same for every @lsr{dir,snippet},
every @internalsref{}, etc ?
Mats, you're the yardstick for efficient NR use. What do you think of
the compact vs. full sentence form of @seealso ? I don't want to
approve any change that makes the NR harder to use for knowledgeable
users, and IMO this is one such change.
In my opinion, the main issue is not how chatty the @seealso is but
rather how
much information you include and where you place it. Regarding your current
version of "Durations", I think it's great to mention about and
reference to all these
issues that are related to the main topic of the section. One question
is if this information
should be below @seealso or in the main text. I have previously mainly
thought of
the @seealso as a kind of reference list ("bibliography") as it is used
in scientific
papers, i.e. a collection of all cross references mentioned in the main
text.
In "Durations", you instead use @seealso to introduce new
concepts/issues that
have not been mentioned in the main text and I kind of like the idea of
putting
these in an item list, where they are easier to spot than in running text.
Still, for cross references that have already been mentioned in the main
text,
it would seem chatty to repeat part of the information again in @seealso.
For the link to "Proportional duration", for example, it's probably
necessary
to provide the concept in a full sentence, so the readers realize what the
link is all about. For "Writing rests", on the other hand, it's pretty
obvious
from the section name itself.
I'm not sure what the conclusion is, but maybe we can reformulate the
original
question into:
- Should we introduce some new concepts under @seealso or should this
always be done in the main text?
- For issues that are somewhat peripheral and just need a short intro and a
cross reference, should they be described in running text or in an
item list?
- Under @seealso, can we find a nice layout that allows for a mix of
pure links
which already have self-explanatory names, with links that need a
sentence of
explanation?
- Is there a need to repeat all links from the main text also in @seealso?
A side comment: in "Durations" under @refbugs, the term "glyphs"
is used several times. Is this is term that is well-known to all readers, or
is it only known to hackers?
/Mats
___
lilypond-user mailing list
lilypond-user@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: chattiness in @seealso
Eyolf Østrem wrote:
On 15.11.2007 (16:19), Graham Percival wrote:
... I _really_ think this is completely unnecessary, though. And if you
want to add full sentences to every single notation reference @ref{}, I
assume you want to do the same for every @lsr{dir,snippet}, every
@internalsref{}, etc ?
No, not really. My only concern -- since you asked for general principles
-- is that there shouldn't be a rule to preclude explanation where it is
desirable.
That's why I proposed #3 -- short explanations could be added if needed,
but most of the time you wouldn't need any explanation. To take the
current examples, if you're looking at Durations and see a link to
"writing rests" (or simply "rests", which is what we should have there),
I don't think there's any question about why it might be useful.
Also, remember that this is the format inside the @seealso -- not about
having links in the main doc section.
Cheers,
- Graham
___
lilypond-user mailing list
lilypond-user@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: chattiness in @seealso
On 15.11.2007 (16:19), Graham Percival wrote:
>
> At the very least, I want it clear which sentence refer to the Notation
> Reference, and which sentences refer to the other parts of the docs.
Agreed.
> ... I _really_ think this is completely unnecessary, though. And if you
> want to add full sentences to every single notation reference @ref{}, I
> assume you want to do the same for every @lsr{dir,snippet}, every
> @internalsref{}, etc ?
No, not really. My only concern -- since you asked for general principles
-- is that there shouldn't be a rule to preclude explanation where it is
desirable. This will be the case, I imagine, with references to some
complicated function in an altogether general section, or in other cases
where the reference in its barest form is less than obvious. In many cases,
I agree that an extra description will be fluff and should be avoided.
> Mats, you're the yardstick for efficient NR use. What do you think of
> the compact vs. full sentence form of @seealso ? I don't want to
> approve any change that makes the NR harder to use for knowledgeable
> users, and IMO this is one such change.
How do you define a knowledgeable user in this respect? One who is
knowledgeable in using the docs will know to look for links in the seealso
sections, and I can't see how it would make it more difficult to use it
with an extra pointer or two (like "Remember to bring the towel from your
hotel room") -- and one as knowledgeable about LP as Mats probably won't
need those links in any case :)
sorry, the question wasn't for me, so I'll shut up.
Eyolf
--
Life, like beer, is merely borrowed.
-- Don Reed
___
lilypond-user mailing list
lilypond-user@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: chattiness in @seealso
On 14.11.2007 (16:18), Graham Percival wrote:
> I think we should have a consistent format for the NR; which one do
> people prefer?
> I have a slight preference against #2 (sentences everywhere), since IMO
I know you have, and you know this is the one I prefer. Giving a hint at
WHY one should seealso ain't fluff. This isn't dungeons and dragons ("you
are in a dark cave. To the east there is a link to Proportional notation,
to the south is a snippet." etc). In other words ...
> in most cases it's obvious why somebody might want to look at other
> section.
... I'd say that in SOME cases it's obvious, but in many it's not, and if a
general rule is needed, I'd go for 2 (with 3 as a variant).
eyolf
--
Law always chooses sides on the basis of enforcement power. Morality and
legal niceties have little to do with it when the real question is: Who has
the clout?
-- Bene Gesserit Council Proceedings: Archives #XOX232
___
lilypond-user mailing list
lilypond-user@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: chattiness in @seealso
Eyolf Østrem wrote:
On 14.11.2007 (16:18), Graham Percival wrote:
I have a slight preference against #2 (sentences everywhere), since IMO
I know you have, and you know this is the one I prefer. Giving a hint at
WHY one should seealso ain't fluff. This isn't dungeons and dragons ("you
are in a dark cave. To the east there is a link to Proportional notation,
to the south is a snippet." etc).
I think you mean "this isn't zork", not D&D. :)
in most cases it's obvious why somebody might want to look at other
section.
... I'd say that in SOME cases it's obvious, but in many it's not, and if a
general rule is needed, I'd go for 2 (with 3 as a variant).
Well, you're the one who'll have to go through and write sentences for
every single @seealso section, so it's no skin off my back... what about
the new Durations? (see tomorrow's GDP; should be online in about two
hours. If you're not certain if you're seeing the updated ones or not:
the updated one stick things in an itemized list)
At the very least, I want it clear which sentence refer to the Notation
Reference, and which sentences refer to the other parts of the docs.
... I _really_ think this is completely unnecessary, though. And if you
want to add full sentences to every single notation reference @ref{}, I
assume you want to do the same for every @lsr{dir,snippet}, every
@internalsref{}, etc ?
Mats, you're the yardstick for efficient NR use. What do you think of
the compact vs. full sentence form of @seealso ? I don't want to
approve any change that makes the NR harder to use for knowledgeable
users, and IMO this is one such change.
Cheers,
- Graham
___
lilypond-user mailing list
lilypond-user@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: chattiness in @seealso
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
Re: GDP: chattiness in @seealso
2007/11/15, Graham Percival <[EMAIL PROTECTED]>: > I have a slight preference against #2 (sentences everywhere), since IMO > in most cases it's obvious why somebody might want to look at other > section. I don't! I like full sentences :) > Option #3 is preferring no explanation at all, but allowing short > phrases in parentheses. IMHO this is the best choice, by far. Valentin ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
GDP: chattiness in @seealso
As always, GDP: http://web.uvic.ca/~gperciva/ (another overdue discussion question, sorry) 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 think we should have a consistent format for the NR; which one do people prefer? I have a slight preference against #2 (sentences everywhere), since IMO in most cases it's obvious why somebody might want to look at other section. For example, if you're looking at Durations, it should be pretty obvious if you personally want to look at: Writing rests, Ancient notation, or Proportional notation. I'll grant that the link to Vocal music might need some explanation, though. Of course I'm famously (and in most of your opinions, unnecessarily :) opposed to fluff. Option #3 is preferring no explanation at all, but allowing short phrases in parentheses. ie 1.2.1 would turn into this: -- See also Notation Reference: Writing rests, Ancient notation (for \maxima), Proportional notation, Vocal music (for specifying durations with lyrics). Cheers, - Graham ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
