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

[Glyph]

On Mar 22, 2012, at 9:18 PM, exarkun at twistedmatrix.com wrote:

> On 19 Mar, 09:10 pm, glyph at twistedmatrix.com wrote:
>> 
>> On Mar 18, 2012, at 9:44 AM, exarkun at twistedmatrix.com wrote:
>>> 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 ;-).
> 
> I can certainly make sure this doesn't happen again in the future. :)

That reminds me, on the subject of documentation, perhaps this could use a little broader discussion:

What do you folks think of my feedback here, in review point 3 specifically?

	<http://twistedmatrix.com/trac/ticket/5248#comment:8>

There are lots of low-level features which get added only partially for their utility in their own right, and partially in support of more general, higher-level features in the future.  I think that in some cases (specifically, in low-level technical cases), it's better to really push for exhaustive reference documentation that explains the motivation of the feature in the API than to add narrative documentation which will potentially clutter the index with (initially) difficult and low-level ways to do something, and (later) TIMTOWTDI advice on how to accomplish the same thing that is better covered by a high level tool.

Another way to handle this situation would be to require narrative documentation initially for the low level features, then eliminate or obfuscate the path to it so that it's not directly present in the general index for its particular dot product[1] when the higher-level feature arrives, or it's present in an obviously de-emphasized section that readers won't find first.  This seems like makework to me, but then, experience generally points to the fact that some of these low-level APIs will be available for years and years while the dreamt-of high-level utopia never arrives.  (c.f. inotify vs. listenFilesystem, IRCClient vs. a truly general, well-documented twisted.words.im, etc)

My current feeling is that people who know that they need to, for example, hand a pre-existing listening socket to the Twisted reactor on a POSIX platform probably know enough about what they're doing to easily find it in the reference documentation.  But I can also see the point of "we should just have lore docs for everything, always", sort of.

So: thoughts?

-glyph

[1]: I'm bringing it back!  <http://tm.tl/2372>


-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20120322/31dee9e3/attachment-0001.html>