Hi all,
In the past, there have been periods of half a year (or more) when Mats
and I suggest that users should read the development manual instead of
the stable manual. Most of the changes I make to the manual apply to
the stable branch as well, but due to technical and time
considerations, I only make changes to the devel manual. These changes
_could_ be backported to the stable manual, but it would be really
tiresome to sift through all the differences and determine which parts
should be backported and which parts cannot.
I see four ways of dealing with this:
1. Status quo. Problem: new users get confused by things I've already
fixed in the devel manual. This is frustrating for both them and me --
late in the 2.7 series, there were many questions on -user about issues
which I'd clarified in the 2.7 manual, but not in the 2.6 manual.
2. Much shorter devel periods (say, four months). New users still get
confused and ask questions about things which I've already clarified,
but there's much less fixed material. Problem: this would cause great
problems for the programmers, particularly since the next release is
3.0 and we want to change lots of stuff.
I'm not seriously proposing this one; I'm just including it here for
the sake of completeness.
3. Once a month, somebody goes through the tiresome process of sifting
through differences between the devel and stable manuals, and backports
whatever is appropriate. If somebody wants to volunteer to do this,
fine; I'm not willing to do it.
4. For the first half of the development cycle, don't include new
features in the manual. New things get listed in NEWS, but only there.
I favor this solution. At first glance, it might suggest that new
features won't get documented well, but it should have the opposite
effect: when I _do_ sit down to move new features from NEWS into the
manual, I'll be doing them all at once, so I won't miss anything. I
think we still have features introduced in 2.2 that haven't made it
into the manual (I'll be calling for a volunteer to do this soon).
This solution also improves the stable documentation -- if the devel
and stable docs remain in synch for another few months, the stable docs
will be in much better shape when I stop working on them.
Just to make sure that I'm totally clear, I'm proposing that new
features don't go into Documentation/user/*. They get listed in NEWS,
and obviously in input/regression/ and/or input/test/ .
Thoughts?
- Graham
_______________________________________________
lilypond-devel mailing list
[email protected]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
