<br><br><div class="gmail_quote">On Fri, Jan 28, 2011 at 1:33 PM, Glyph Lefkowitz <span dir="ltr"><<a href="mailto:glyph@twistedmatrix.com">glyph@twistedmatrix.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
<div style="word-wrap: break-word;"><div><div></div><div class="h5"><br><div><div>On Jan 28, 2011, at 10:38 AM, Kevin Horn wrote:</div><br><blockquote type="cite"><br><br><div class="gmail_quote">On Fri, Jan 28, 2011 at 7:25 AM, Itamar Turner-Trauring <span dir="ltr"><<a href="mailto:itamar@itamarst.org" target="_blank">itamar@itamarst.org</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
<br><div>
A service is supposed<br>
to be something you can start and stop, and encapsulates a<br>
self-contained piece of business logic.
</div><font color="#888888"><br>
-Itamar<br>
</font><div><div></div><div><br>
<br></div></div></blockquote><div><br>This or something very much like it should be in the Twisted Glossary.<br><br>Kevin Horn <br></div></div></blockquote></div><br></div></div><div>The whole idea of a glossary concerns me a little bit. </div>
</div></blockquote><div><br>You're just saying that because you don't want anyone else to understand what you're saying ;)<br><br>Seriously though. When I first started thinking about ways to improve the documentation. The _first_ thing I thought was missing was decent explanations of some of these things. Whether it's in a glossary or someplace else, clear definitions need to exist for all the major Twisted concepts (people may disagree on what is or is not major, and that's fine). Putting these definitions (or links to them) in a glossary keeps them all together and easy to find and refer to. One of the first thing I look for in any software documentation is a glossary or some set of definitions that I can refer to while I'm _reading_ the API docs or whatever.<br>
<br>Solving problems through software requires finding the right abstractions, which IMO depends a great deal on finding the right vocabulary for those abstractions. I know the Twisted devs spend a lot of time and energy trying to find exactly the right word for a class, or a method, or whatever. Let's communicate that to new people! If you don't want a "glossary", then we'll do something else, but I think it's important to have all of the really critical concepts described in one place somewhere.<br>
<br>Also consider the problem of reverse human lookup: "Oh man, what was that thing called that stops and starts Twisted code at the appropriate times?"<br><br>If you stick that into a search engine, you probably won't find it for a loooong time. But if there's a glossary, you just look there, and you find it pretty easily.<br>
</div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;"><div style="word-wrap: break-word;"><div>One way I frequently see it done is vague little snippets of text like this, and I don't like that. </div>
</div></blockquote><div><br>Well, I consider it much more meaningful than what is currently there. Not saying it's really sufficient, but it is succinct. I think what I'd like to see is a "glossary" entry with:<br>
<br>- an API link (e.g. "An object which implements the IService Interface" -- and yes, it should be a proper English sentence.)<br>- A succinct definition (like Itamar's quip above)<br>- a paragraph or two of discussion (not too long though!)<br>
- "see also" links to HOWTO's etc.<br><br>I want to say that I do NOT think we should be trying to include every single idea/concept/interface/class/whatever in whatever glossary comes up. Just the main concepts.<br>
<br></div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;"><div style="word-wrap: break-word;"><div>Not to say that Itamar's answer to this particular question was incorrect or inappropriate, I just wouldn't want to see this enshrined as the official, central definition.</div>
<div><br></div><div>However, Twisted does have its own jargon and a dictionary to help the novice parse it would be a good thing.</div><div><br></div><div>What I'd really like to see in this regard is to make sure that every "jargon term" is linked straight to API documentation, since we've gone to some trouble to make our jargon match the names used in code as closely as possible*. In this case, <<a href="http://twistedmatrix.com/documents/10.2.0/api/twisted.application.service.IService.html" target="_blank">http://twistedmatrix.com/documents/10.2.0/api/twisted.application.service.IService.html</a>>. If the API documentation is not sufficient (which in this case it may well not be), let's make the API documentation sufficient<i>.</i> Don't fortify it with a redundant official glossary listing that has to be maintained in parallel and updated in synch with the API docs.</div>
</div></blockquote><div><br>I'm not sure how much of a problem maintaining it would be, especially as I agree that linking to the API docs is probably a good idea (though I think a lot of the docstrings in there could be greatly improved). For one thing, how often has the _intent_ of the IProtocol interface (which has no docstring, btw) changed? And how often does someone show up on IRC who doesn't understand what a Protocol object is show up?<br>
</div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;"><div style="word-wrap: break-word;"><div></div><div>Thoughts?</div><div><br></div></div>
</blockquote></div><br>I think we've totally hijacked this thread :)<br><br>Kevin Horn<br>