[Twisted-Python] [Twisted-commits] r33889 - Merge elementresource-5395: Add renderElement, for rendering Elements.

Glyph glyph at twistedmatrix.com
Mon Mar 19 17:10:27 EDT 2012


On Mar 18, 2012, at 9:44 AM, exarkun at twistedmatrix.com wrote:

> On 02:20 am, glyph at twistedmatrix.com wrote:
>> 
>> On Mar 17, 2012, at 7:53 AM, Itamar Turner-Trauring wrote:
>>> On 03/16/2012 10:51 PM, dreid at wolfwood.twistedmatrix.com wrote:
>>>> Author: dreid
>>>> Date: Fri Mar 16 20:51:46 2012
>>>> New Revision: 33889
>>>> 
>>>> Added:
>>>>   trunk/twisted/web/topfiles/5395.feature
>>>>      - copied unchanged from r33888, 
>>>> /branches/elementresource-5395/twisted/web/topfiles/5395.feature
>>>> Modified:
>>>>   trunk/twisted/web/template.py
>>>>   trunk/twisted/web/test/test_template.py
>>> 
>>> I notice no documentation was added. Perhaps we should start requiring
>>> documentation updates for all new features?
>> 
>> Before the ticket was closed, a separate ticket was filed for 
>> documentation: <http://twistedmatrix.com/trac/ticket/4983>.
>> 
>> I don't think that adding a hard requirement for documentation on every 
>> new thing as a prerequisite is necessarily a good idea (especially if a 
>> new contributor wants to add a feature, this adds to an already 
>> substantial burden), but someone should ask a question about 
>> documentation on any ticket that doesn't explicitly account for it, 
>> very early in the process.
> 
> The way I feel about documentation now makes me read this much as I 
> would read a different response to a different question.
> 
> You should be able to guess the question from my imagined response:
> 
>    I don't think that adding a hard requirement for unit tests on every new
>    thing as a prerequisite is necessarily a good idea (especially if a new
>    contributor wants to add a feature, this adds to an already substantial
>    burden), but someone should ask a question about unit tests on any ticket
>    that doesn't explicitly account for them, very early in the process.

Yes, yes, how droll :-P.

> As usual, I can't prove that writing documentation at the same time (or 
> before) an implementation actually produces better results, but I can 
> say that this is increasingly my opinion from my personal experience.
> 
> *Even* if requiring documentation cut feature contribution by half, I 
> think it'd be worthwhile.  Some number of features, undocumented, are 
> worth less than half as many with good documentation.

Actually I agree with that.  What we need is not more contributions, but more contributors (especially, more qualified reviewers).  I have the vague sense (which I also can't prove) that contributors stick around more often if they are able to successfully contribute something, and needing to become familiar with a new documentation toolchain in addition to a new testing toolchain is an impediment to that.  The flip side of that is that more contributors will probably show up in the first place if the documentation is better.  So I am somewhat ambivalent and am easily swayed by the argument that we already do apparently require it.  Still, I think we should try to bring it up as early as possible in the review process, and have better docs on how to author docs.

> Plus, note that it was not a new contributor who finished this 
> particular ticket. ;)

Re-attracting idle contributors has even more appeal, as maybe they'll remember how to review tickets :).

> Also, note that http://twistedmatrix.com/trac/wiki/ReviewProcess already 
> says, as "Things your branch must contain":
> 
>    Appropriate new or modified "End User" guide documentation (in the form
>    of Lore-formatted xhtml files in the doc/ directory)
> 
> So essentially we do require this already, but reviewers seem to largely 
> ignore it (so even if we decide this should not be a requirement, 
> reviewers are not doing their job properly, and that's another issue we 
> should address).
> Jean-Paul

Looks like some guy named "exarkun" was the passing reviewer on the ticket in question, maybe you should talk to him ;-).

-glyph




More information about the Twisted-Python mailing list