[Twisted-Python] Questions about adding documentation

[Steve Steiner (listsin)]

On Aug 2, 2009, at 12:41 AM, Glyph Lefkowitz wrote:

> 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.

Ok, fine, it went "over there."  Now...if you're just starting out,  
how much does "over there" help and how much has "over there" ever  
been integrated into anything else?  How would you even find "over  
there?"

I guess I'm still frustrated with the lack of an overarching doc  
organization scheme.

I've tried to use various parts of the Twisted eco-system, on a number  
of projects, and have repeatedly gotten stuck on outdated, disjointed,  
disorganized, and just plain wrong documentation.

As I've said before, the complete lack of date/version stamping on  
example code has been the greatest source of frustration.

I've, more than once, gotten half-way through a tutorial and realize  
that it just plain didn't work with the current version.

End of exploration.

I used the best result I found in my search and it just didn't work.   
Gotta move on; client's getting annoyed.  Unbillable time; bad.

> 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 :).

Hasn't happened, and isn't going to happen, in my opinion, until  
there's some actual incentive for "people in the community", which is  
a small subset of the "potential community", to actually do anything  
about it.  Documentation is not needed by the "community" as much as  
it's needed by the "potential community."

> 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.

Frankly, the work is boring and it ain't happening, never has, and  
never will unless something changes.  Bounty system, torture, Target  
coupons, whatever...

> 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.

See above.  How many years does the same thing have to happen for  
there to be a realization that, without a fundamental change, nothing  
is going to happen?

If you paid someone, 20 hours a week, to babysit the documentation  
effort, they would.  Depending on their competence, there would be  
progress.

If you wait, endlessly for "Once we have people taking part in that  
effort and working with the docs on a daily or weekly basis", you're  
going to get the same result.

> 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.

I'm not sure what I'm interested in, at this point, but I certainly am  
not interested in doing it for free and neither is anyone else.

In my opinion, and by existing evidence, coherent documentation ain't  
happening, and won't, unless something fundamental changes.

It's not my project and it's not for me to decide but it seems to me  
that waiting for "people to take part in that effort" is doomed to  
waiting forever...

S

-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20090803/7df8093e/attachment-0001.html>