doc branching

[Graham Percival]

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