David,
Sorry for the long response, but maybe it will be useful for project insiders
to see how someone mostly on the outside experiences the documentation and the
ways for finding things.
I think part of the problem is the sheer volume and being able to recognize
what is directly relevant. For those who are immersed in the project there is a
logic and clarity that those coming from outside may not always see. My need is
sporadic. I may go six months and not touch Lilypond and then need it
extensively for three weeks and then go another six months. That means I am
consistently relearning things (although fewer things each time).
(Incidentally, I just found this page - http://lilypond.org/web/documentation -
that is rather sorely out of date. I'm guessing it is an old, orphaned page?)
> There is a table of contents,
OK, fair enough, but, using my case as an example, take a look at the TOC and
ask yourself if you could find the appropriate point using it if you did not
already know where it was. My guess is the answer would be no.
Searching for "rest" brings up zero hits in the TOC as it first appears. Now if
I do click into 1.2 Rhythms, I get to 1.2.2. Writing Rests. I actually had
looked through this a number of times while working on this piece, but never
made the connection that I should look under the heading Positioning
multi-measure rests to determine how to change the default position of plain
rests. (Note that this section does not actually address how to change the
default position of plain rests and even Phil, when chiding me for not using
the index, himself had to extrapolate from the one section to the general
solution.)
Now, as it happens, one can extrapolate the needed information from that
section, if one makes the leap to say “maybe this bit applies to my similar,
but not identical, situation” and if one knows how to make that extrapolation.
But that is an inferential leap I did not happen to make.
There is no obvious path (at least to someone not immersed in the project) to
get from "rests in my piece are showing up in the ‘wrong’ place and I want to
change the default” that leads to the solution via the TOC.
> there is an index,
The index might have helped. However, because of the layout of site and my
screen size, it was hidden from view for me. I simply did not know it existed.
If I may be so bold as to make a suggestion, perhaps the Index link could be
put at the top of the TOC to encourage its use.
Leaving that aside, had I seen it and looked up rests, I would have found rest,
specifying vertical position, which sounds promising indeed, but which does not
address the question of setting defaults and indeed tells me what I already
knew about constructs like b4\rest that I was using.
The other one I would have tried was rest, collisions of. Interestingly enough,
that links to an anchor over the single sentence in the Known issues and
warnings section that reads “Multi-measure rests do not take part in rest
collisions.” I'd actually argue that that link doesn't even make much sense and
that content higher up in the page is more relevant from a user perspective to
the index heading than what it actually links to.
Again, the index might have helped me if I already knew what I needed to find.
But for the outside user who doesn't know it, there isn't much helpful there.
Phil was able to find things because he already knew enough to use the index to
find something different that happened to suggest the solution.
> there is plain text search.
This, again, was hidden from me and I actually wondered why there was not a
plain text search. I had been using plain Google to find things because I
didn't spot that search field hidden well below the edge of my screen. Perhaps
I should have scrolled down and seen it, but I did not. From a usability
standpoint, the search field is wasted at the bottom of the page and should be
made much more prominent. If anything I write in this mail has value, that
should be it.
However, if I use it (now that I know about it) and search for "rest position,"
none of the hits are obviously relevant from the Google summaries except for
the first one, but I'd already read that page and not made the connection that
was needed.
> The index contains "rest, specifying vertical position".
As mentioned above, that addresses the solution I already knew about, but does
not actually address how to set the default, which is what I was looking for.
(I just triple checked to be sure.)
> There is also the analogous "positioning multi-measure rests".
And therein is the problem. It is analogous, not explicit, and stating that
that is the solution presumes that one understands, while searching, that the
analogy is there to be made. With more care and time, I might have made that
leap. But I was searching the documentation for my particular issue, not a
similar/analogous one.
> So how could this have been made easier?
I don't really know, other than the simple fixes of making the index and search
more obvious in the documentation’s TOC. Those two things would be a start, but
ultimately wouldn't have helped me with this problem.
But at another level, I don't know there is much that can be done until you see
where people have trouble and then augment the documentation. Now that I have,
rather exhaustively, shown why it was not simple to find what I needed, one
could add a section called “Setting the default position of rests” (or at least
provide an explicit statement in the broader section), which would be found in
the plain-text search and by digging in the TOC. But that is fundamentally a
band-aid for a particular problem. (I'd still recommend adding it to the
documentation. A band-aid does have its uses.)
Fundamentally it comes down to the problem that Lilypond does so much and is so
powerful that documenting everything is a rather difficult proposition. You
never know what has been missed and, until someone comes along with a specific
need that isn't intuitive in what is written, the gap may never appear. There
is fundamentally no way to know that you have covered everything.
That is probably far more than you wanted, but maybe it is useful. At the least
it does give me the satisfaction of demonstrating (to myself and to others)
that it was not laziness that kept me from finding the answer, but rather a set
of real issues with how I interacted with the documentation and a lack of
clarify in the documentation on this issue.
Best,
Arle
_______________________________________________
lilypond-user mailing list
lilypond-user@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-user
