[Twisted-Python] Questions about adding documentation

Glyph Lefkowitz glyph at twistedmatrix.com
Sun Aug 2 00:41:02 EDT 2009


On Sat, Aug 1, 2009 at 11:30 PM, Steve Steiner (listsin) <
listsin at integrateddevcorp.com> wrote:

> Where would we put an "inventory" project for it to be most useful?
>>
>
>  As JP mentioned earlier in this thread, some work has already taken place
> here: <http://twistedmatrix.com/trac/wiki/DocumentationAnalysis>.
>
>
> It doesn't really look like that effort went anywhere.
>

I don't think it's quite fair to say it didn't go *anywhere*, it just didn't
get anywhere particularly complete.  I think the reviews that have been done
thus far are still a valuable resource for someone interested in working on
the documentation.


> Maybe we should have an auction?
>

(snipped lengthy description of labor-intensive bounty resolution process)

What we really need is for people in the community to knuckle down and do
the work of actually reviewing the documents, rewriting things, soliciting
feedback, copy-editing the documents, checking for accuracy, etc.  As
Jessica did when she started the thread :).

Frankly, the work is boring: what the documentation needs is not a dynamic
market-driven system for managing contributions and paying bounties, it's
not a comprehensive overhaul of our entire documentation toolchain.  What it
needs is for people to sit down and read all the documentation, make a list
of all of its problems, one at a time, and then write, delete, and edit as
necessary, incorporating feedback from the community.

Once we have people taking part in that effort and working with the docs on
a daily or weekly basis, *then* we can listen to the reality of the problems
and frustrations that they have working with the tools or determining
priorities or whatever and solve those problems.

Separately from that, if you're interested in contributing some time to
manage a bounty program for the TSF, that might be a reasonable idea.  Other
projects have experimented with bounty-based systems for resolving bugs.
Unfortunately there are a number of difficulties with those systems, which
are really out of the scope of this discussion, but they're worth talking
about if you have a real interest in doing it.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://twistedmatrix.com/pipermail/twisted-python/attachments/20090802/ccab5b33/attachment.htm 


More information about the Twisted-Python mailing list