[Top][All Lists]
[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