[Twisted-Python] Refactoring Documentation

[Glyph Lefkowitz]

On Jan 20, 2011, at 1:54 PM, Kevin Horn wrote:

> The biggest problem with this is that you will find that a very small group of people have created the vast majority of this stuff and don't have time to maintain it all any more :).  We certainly don't have a separate dedicated maintainer for each project (although I really wish we could get to that point).
> 
> I think this right here is the main reason that the docs need to be improved.  Easier newbie experience translates to more users translates to more developers translates to more maintainers.  Especially if the perception of Twisted as a "languishing" or even "mostly dead" project can be undone. (Yes, I've heard this a number of times.  No, I don't know where they get it.  I correct it whenever I can. It's something that needs to be addressed, but that's a different conversation.).  Fixing up the docs will at least help with this.

Wow, that is weird.  Maybe in the meanwhile, refer people with this peculiar misconception to <https://www.ohloh.net/p/twisted> - "Large, active development team", "Mature, well-established codebase".

(Also tell them to click "I use this".)

>> Most of this was discussed with Jean-Paul and Glyph at tonight's Python meet-up in Cambridge. Some work has already begun on the new docs here:
>> 
>> https://github.com/tdavis/twisted-docs
> 
> There have been several abortive efforts to do something grand to re-invent all of the Twisted documentation in the universe, or a complete overhaul of the website, including several false starts that I've made, and most recently the (somewhat arduous, arguably "mostly complete" (fingers crossed on that one)) attempt to do a sphinx migration.
> 
> Seriously man, we're close.

So prove me wrong, and get it done! ;-)

> 3 more "chunk tickets" in the "edit the lore source" phase (and one of those is finished I think and just needs to be merged).  Then another round of "chunk tickets" to manually fix any other little typographical issues in the Sphinx source, and done.  I suppose there will also need to be a website deployment process.  And probably lots of other minor things that we'll discover as we go.

I think that the main problem right now is that these "chunk tickets" are too big, and especially with the sphinx builder in this half-working state, nearly impossible to review.  As Jean-Paul were recently discussing, he bit the bullet and plowed through one of these (overlarge) ticket reviews, assuming "how much of a problem could it be, it's just whitespace", and ultimately (after trying his best to examine it closely) gave it a passing review.  And yet, there were still a couple of bugs filed that were introduced by that branch, including things like word being accidentally deleted.

Breaking these up even more into smaller, easier-to-digest fixes, and then having a docs review sprint, should be able to get us over that hump.

> I've had some major speedbumps, had to find a new job, kids were sick several times, etc.  You know...life.

No worries.  That's why we've been taking this conservative approach :).

> I'm getting fired up again though, and thijs seems to be as well, and this coming up now just pumps the bellows.

Yes!  Woo!

> It looks like Tom and I have some similar ideas on where we should be going, and I think his Sphinx skeleton is a great example of what things should eventually look like.  As I said earlier, I've had a number of similar ideas, though it looks like maybe Tom's are a little more concrete and/or fleshed-out.  I just really wanted to get the Sphinx convo "out the door", before I took on another huge project.  I'll elaborate in a separate email.

+1

> There's a ticket for writing tests for the code samples in Trac.

Always good to have a link: http://twistedmatrix.com/trac/ticket/2205

> My advice is to try and get many small changes made, and get them _done_ rather than a few huge changes.

I think I want this to be on my tombstone :).

> I think this has been pretty constructive on both sides.  I look forward to more.

Same here.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20110121/a1227ae5/attachment.html>