[Twisted-Python] Refactoring Documentation

[Glyph Lefkowitz]

On Jan 20, 2011, at 11:20 PM, Tom Davis wrote:

> I definitely agree that resolving the low-hanging fruit first is a good idea. For finishing "docs branch X" to make sense, my personal belief is that X should:
> Still be relevant in terms of best practices and simply what's available
> If project documentation, have outstanding issues that a passing familiarity with the project [right now] will be sufficient to close them (I could spend time learning one project, or the same time improving all the documentation)
> Adhere to whatever documentation standards we agree upon, if much is to left to do.
> I guess my overall opinion here is that, yes, if relatively minor edits can bring a branch close enough to completion that we can get it out there to help newcomers now, let's do that. If a branch is more of a draft and requires a good deal of fleshing out (or is simply stale), it's probably worth nailing down the structure and previously mentioned docs standards before I just create more work for myself (or others) down the road.

If branches that are out there don't meet these standards, commenting on their tickets and getting them deleted or closed as invalid (as appropriate) would be a big help too.  Lots of languishing tickets that nobody knows what to do with is not a good thing, and there's plenty of opportunities for interested parties to reopen tickets, attach new patches, and object in various ways, so you shouldn't be too concerned about stepping on toes.  Focus is a valuable commodity.

Part of my comment about low-hanging fruit was to help you get familiar with and integrated into the development process.  Going through the process of getting patches reviewed and accepted will be _much_ easier if you go through the motions of doing a few trivial things first.  In fact you may want to just pick up a couple of trivial non-docs patches as well, which might help you on documenting the development process :). <bit.ly/easy-twisted-tickets> might help you there.

Mostly, I really don't want you to write a gigantic pile of new documentation and then find, when you're "done", that you missed some nuance of the coding standard, or the patch is too big to be reasonably reviewed, and that now you have three months of additional work to do before it's all really done.  Experience with the process will mitigate that problem significantly.  (And in fact I hope that you don't actually have a gigantic pile of stuff to commit all at once at any point, and can continue this work incrementally as a series of small tickets, but I realize that later on some of the index reorganization stuff may need to be big.  This is mostly just restating what Kevin already said in his message, but it bears repeating.)

> Finally, my biggest hurdle right now is not knowing how to find said branches. I don't see "documentation" as a category in Trac and common keyword searches didn't show up much for me. I'm sure this is an easy question to answer, though.

<http://twistedmatrix.com/trac/query?status=assigned&status=new&status=reopened&order=priority&col=id&col=summary&col=status&col=owner&col=type&col=priority&col=milestone&keywords=%7Edocumentation>

There is, unfortunately, no "has branch" column in that report, but it will at least give you some data to work with.


> What should a newcomer who reads this document know by the end of it?
> 
> I'm not sure because I can't see how a practical guide to creating something so generic really fits in the grand scheme of things. I think if you want to create a TCP server from scratch you must first create the Universe! In this case, that means learning how Twisted addresses the concept of a server before ever bothering to write one so generic. My general beef is that many documents seem to make an attempt to appeal to everybody and in doing so don't sufficiently help anybody. Maybe I can justify that claim better with examples of "better" (at least more targeted) documents.

I don't think you need a clear definition of "better" for this particular document, if it doesn't really fit into your scheme; I don't mind if it eventually becomes irrelevant.  I just want a clear statement of goals for the documentation _in advance_ of writing that new documentation, so that we can discuss whether it's actually better for the intended audience or whether it's just more suited to a new author's tastes.

> You will probably have to press us core developers on this one, and you may spark some debates. These tend to sputter out with no clear resolution as everyone is frustrated that nobody's solution (not even their own) is ideal, but you would be doing us all a great service if you really forced us to develop a consensus about certain things (like "what's the best way to build a twisted command-line program", for example) and agree to agree on the current documented "best practice" for those things.
> 
> Debates are great!

Debates that reach some kind of conclusion are great :).  Debates that just go in circles until everybody feels crappy about the topic aren't.  So I'm really just asking you to help us make these debates into the great kind.  (The rest of your reply seems to agree with that, I just wanted to be clear.)

> 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).
> 
> Kevin touched on this already, but I really think if we make maintaining and growing a Project something that is both honorable and accessible, more people will want to do it.

Okay, so, this is really a tangent, but maybe you could let me know what you think of <http://tm.tl/2372>.

> If you like Python and DNS or SMTP or whatever the hell else, what has the potential to be a more awesome implementation than its Twisted one? Let's help people find out for themselves that the answer is nothing. Then they'll want it to be their project.

If you do this, you will be my hero forever.

OK, I'm going to skip the rest of the reply so that I don't write another book-length thing here, and I agree with most of the rest of what you've said.  So get to it!
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20110121/538fc99e/attachment-0001.html>