[Doc-SIG] that library reference, again

[Ian Bicking]

Fredrik Lundh wrote:
> (I'm not sure if it's python.org or gmane.org that has trouble right now,
> but something's wrong somewhere.  let's see if this works better)
> 
> Ian Bicking wrote:
> 
> 
>>>fwiw, I'm not convinced that we need a tracker at all.  A mailing list
>>>and a way to link to documentation constructs (with links that can
>>>be read and written and followed by humans, and identified by com-
>>>puters) might be good enough.
>>
>>I think there needs to be at least some workflow, some way to indicate
>>what comments have been acted upon and which ones have not.  How else
>>can multiple people maintain the documentation?  There's no
>>collaborative way to track the status of email messages.
> 
> 
> I somehow assumed that the maintainers would use email to report back to the
> list ;-)
> 
> the problem here is to strike a balance between tracking and discussing; trac
> and roundup etc are great tools if you want to track progress for
> distinct issues,
> but they're not that great for discussions, especially when you don't
> know up front
> if the discussion is going to result in a single issue, a dozen
> issues, or nothing
> at all...

Roundup is pretty good for discussions, since it has an email gateway. 
I think Roundup would be just as good a choice as Trac.  A gateway 
doesn't deal with the case when a single discussions involves many 
tickets (or vice versa), but I think ad hoc ways to deal with that 
(e.g., create a new expansive ticket, or just track it manually) are 
generally fine.  That said, I've also seen people usefully discuss 
things on trackers, it's just not the default.

The main workflow issue I see is how to defer work without forgetting 
it.  I know I personally am horrible at doing this with email -- if I 
don't handle it right away I forget about it.  Assignment can be quite 
useful in collaboration, when you want to either say "I am working on 
it", or "you should work on it", and doing that in email is also hard, 
especially more than once (you have to find the latest 
assignment-related email to figure out who has the ball).

Also, discussion doesn't seem primary to this.  Most comments can 
probably be acted on directly with no discussion.  So optimizing for 
discussion seems wrong.

-- 
Ian Bicking  /  ianb at colorstudy.com  /  http://blog.ianbicking.org