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.
_______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
