<html><head></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; "><br><div><div>On Mar 22, 2012, at 9:18 PM, <a href="mailto:exarkun@twistedmatrix.com">exarkun@twistedmatrix.com</a> wrote:</div><br class="Apple-interchange-newline"><blockquote type="cite"><span class="Apple-style-span" style="border-collapse: separate; font-family: Menlo; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-border-horizontal-spacing: 0px; -webkit-border-vertical-spacing: 0px; -webkit-text-decorations-in-effect: none; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; font-size: medium; "><span class="Apple-style-span" style="font-family: monospace; ">On 19 Mar, 09:10 pm,<span class="Apple-converted-space"> </span><a href="mailto:glyph@twistedmatrix.com">glyph@twistedmatrix.com</a><span class="Apple-converted-space"> </span>wrote:<br><blockquote type="cite"><br></blockquote><blockquote type="cite">On Mar 18, 2012, at 9:44 AM,<span class="Apple-converted-space"> </span><a href="mailto:exarkun@twistedmatrix.com">exarkun@twistedmatrix.com</a><span class="Apple-converted-space"> </span>wrote:<br></blockquote><blockquote type="cite"><blockquote type="cite">So essentially we do require this already, but reviewers seem to<span class="Apple-converted-space"> </span><br></blockquote></blockquote><blockquote type="cite"><blockquote type="cite">largely<br></blockquote></blockquote><blockquote type="cite"><blockquote type="cite">ignore it (so even if we decide this should not be a requirement,<br></blockquote></blockquote><blockquote type="cite"><blockquote type="cite">reviewers are not doing their job properly, and that's another issue<span class="Apple-converted-space"> </span><br></blockquote></blockquote><blockquote type="cite"><blockquote type="cite">we<br></blockquote></blockquote><blockquote type="cite"><blockquote type="cite">should address).<br></blockquote></blockquote><blockquote type="cite"><blockquote type="cite">Jean-Paul<br></blockquote></blockquote><blockquote type="cite"><br></blockquote><blockquote type="cite">Looks like some guy named "exarkun" was the passing reviewer on the<span class="Apple-converted-space"> </span><br></blockquote><blockquote type="cite">ticket in question, maybe you should talk to him ;-).<br></blockquote><br>I can certainly make sure this doesn't happen again in the future. :)<br></span></span></blockquote></div><br><div>That reminds me, on the subject of documentation, perhaps this could use a little broader discussion:</div><div><br></div><div>What do you folks think of my feedback here, in review point 3 specifically?</div><div><br></div><div><span class="Apple-tab-span" style="white-space:pre"> </span><<a href="http://twistedmatrix.com/trac/ticket/5248#comment:8">http://twistedmatrix.com/trac/ticket/5248#comment:8</a>></div><div><br></div><div>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.</div><div><br></div><div>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)</div><div><br></div><div>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.</div><div><br></div><div>So: thoughts?</div><div><br></div><div>-glyph</div><div><br></div><div>[1]: I'm bringing it back! <<a href="http://tm.tl/2372">http://tm.tl/2372</a>></div><div><br></div><div><br></div></body></html>