On Mar 22, 2012, at 9:18 PM, exar...@twistedmatrix.com wrote:
> On 19 Mar, 09:10 pm, gl...@twistedmatrix.com wrote:
>>
>> On Mar 18, 2012, at 9:44 AM, exar...@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>
_______________________________________________
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
