lilypond-user
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

GDP: the snippets vs. texinfo


From: Graham Percival
Subject: GDP: the snippets vs. texinfo
Date: Fri, 09 Nov 2007 21:02:50 -0800
User-agent: Thunderbird 2.0.0.6 (X11/20071022)

OK, it's finally time for the big fight!

In managing the docs, I need to weigh multiple contradictory demands.

PDF vs. HTML: pdf readers generally prefer to have consecutive documentation, with few links. HTML readers generally prefer to have links everywhere.

Stable docs vs. wiki: some people want an unchanging, complete, finished set of docs, particularly if they print them out. Other people like the constant flux of web 2.0 stuff.

Me vs. everybody: I want a set of easily maintained docs. I also want to set realistic goals. I feel no compunction about rejecting any suggestion -- no matter how good from a documentation standpoint -- which we do not have the resources (ie volunteer time/effort) to create and/or maintain.


Out of all of these concerns, I naturally feel that my own position is the most important. If anybody wants me to relax my "we don't have the resources to do this" position, please volunteer in GDP. If I have more resources, of course I'll accept more good doc ideas,


Consider NR 1.2.1 Tuplets, for example. (if you haven't already, please see the "LSR->lilypond docs" email)

Currently, the "Commonly tweaked properties" contains five examples. These demonstrate a number of neat tricks you can do with tuplets... but what happens if something needs to be updated? (ie a property name changes, somebody thinks of a better explanation, there's a nicer way to achieve a particular tweak, etc)

1) The helpful user could download the lilypond source, edit rhythms.tely, compile the docs to check that it works, make a patch, send it to -devel. That's a lot to expect from people.

2) The helpful user could send an email explaining what to do, according to the "documentation suggestions" page. I honestly don't think that's too much to ask from helpful users, but in the past two years I've received less than ten such emails. Clearly people are shy about sending emails.


Now, suppose (for the sake of argument) that all of these tweaks were in the "Snippets: rhythms/" link at the bottom of that page. This means that these tweaks are in LSR, and that gives helpful users a third option to fix examples:

3) The helpful users edits the snippet in LSR. The LSR editor is notified about the modified snippet, approves it, and the main lilypond docs are magically updated in a few days.


I confess that I'm not totally convinced that hordes of users are going to follow #3... but whenever I complain about the lack of users helping with the docs (pointing out #2, "all you need to do is send an email to me -- if you can complain about the docs on this mailist, then you can help fix the docs!") I always get people claiming that if there was a wiki, they would be committing updates.


Some PDF users may not be so fond of the snippets because they move material out of the main docs. I'd like to point out that the Snippets are available as PDF, so that might mitigate this concern.


Now that we have the technology in place and a description of how it might work, we need to decide how this affects the docs. In particular, what do we keep in @commonprop, and what do we move into LSR (and the Snippets) ?


My proposal, taking into consideration all the contradictory demands laid out at the top of this email, is to have one or two tweaks in the @commonprop. The main goal of @commonprop is to pique the interest of a reader, to encourage him to follow the "Snippets: foo, bar" links.

For example, in Tuplets I would suggest keeping the first and second-last examples in the @commonprop section, and moving everything else into Snippets. Not because I don't think the tweaks are useful, but just to direct readers to the Snippets, and from there the LSR. Hopefully the easily-updateable LSR will generate a culture of doc-improvement.

Cheers,
- Graham




reply via email to

[Prev in Thread] Current Thread [Next in Thread]