Re: [Condor-devel] how to merge manual

[Erik Paulson <epaulson@xxxxxxxxxxx>]

On Tue, Aug 02, 2011 at 08:43:37AM -0700, Erik Erlandson wrote:
> 
> For the record, I think Tim has a point regarding a policy of freezing
> doc along with code for any given release.  If that implies Karen acts
> as doc wrangler for release branches and is part of release workflow,
> that makes sense from a "1st class citizen" POV.
> 

The problem is that the documentation is both versioned but is allowed to
change independently of any "release" - i.e. the bits that are "released"
as 7.6.0 are unambiguous, but knowing that your manual is 7.6.0 doesn't
tell you exactly what is contained in the manual. 

I don't see the continually evolving manual as a problem - as I've mentioned
before, there are already too many "versions" of the manual on the web 
today and the noise makes it harder to find information quickly. 

Furthermore, if there is prose that can be fixed in the manual today, why in
the Good Lord's name should that have to wait until 7.6.3 is released? And
why would you look at a specific version of the manual anyway? Much of what
needs to be improved in the manual would make life better for users of 7.4, 
7.2, and some even all the way back to 6.2. 

If you find a bug during the 7.6.4 process that was introduced in 7.6.1,
what version of the manual gets updated to explain a workaround? Do you
really update the 7_6_1_doc branch, merge that through 7.6.2 and 7.6.3,
and then through 7.6.4, as well as any development releases?

(Though, at some point, to keep the prose clean, it makes sense to stop
supporting old versions of the code in the manual. I think if you're going
to version the manual, the way to do it is looking backwards, and snapshot
the manual as you drop support for old versions of Condor)

Maybe I just think of it differently - I think of the documentation as what
we put on the web, and stopped caring that it also "ships", with the possible
exception of the man pages. In that world-view, this struggle to figure out
where things get merged seems like a waste of time. Who cares if something
shows up on the web before the code ships? If it's version specific, you have
to clearly explain that anyway. And until we get Miron in a turtleneck, jeans,
and a "One More Thing" slide, I'd rather get info about a feature early. 

Fewer branches, less time in the version control system, more time actually
documenting. 

-Erik