[Zope] documentation defacement

[Fred Drake]

On Tue, 25 Jan 2005 17:00:50 -0500, Chris McDonough <chrism at plope.com> wrote:
> That'd be fine as well.  The only real reason the dev versions are
> Backtalk now is in order to have them available for display to docs
> seekers.  We could maybe just ditch Backtalk/STX altogether, but I'm not

There's no need to move away from STX, and doing so at this point
would be a nuissance.

> sure what the alternative is.  I do think the commenting features are
> valuable, as much as they may be abused.  I'll also note that the last
> change made to the development docs was many months ago, and I'm not
> sure that moving them into another system will improve that in any way.

I've no objection what-so-ever to making the documents annotatable,
though it's not clear to me that BackTalk is the right way to do it. 
The problems I see are:

1. General editing in the non-canonical location is bad, and
misleading for potential contributors.  This is especially true for
occaisional contributors like me.

2. Being able to incrementally update from the maintained version
without losing annotations seems necessary, unless we require that all
annotations be handled or integrated by the time the update is
performed.  Such a requirement is not acceptable.

I don't know if BackTalk can be used that way, or can be easily
modified to do so.

Given the synchonization issue, I'd gladly give up the annotations if
the documents became easier to update, and have the updates actually
make it to the published version (regardless of where that is).


  -Fred

-- 
Fred L. Drake, Jr.    <fdrake at gmail.com>
Zope Corporation