On Jan 29, 2011, at 10:47 PM, Andrew Bennetts <andrew@bemusement.org> wrote:
Glyph Lefkowitz wrote: [...]
The whole idea of a glossary concerns me a little bit. … However, Twisted does have its own jargon and a dictionary to help the novice parse it would be a good thing. What I'd really like to see in this regard is to make sure that every "jargon term" is linked straight to API documentation
We already have a glossary:
<http://twistedmatrix.com/documents/current/core/howto/glossary.html>
Yeah, that came up a bit later in the thread :). And kevin did mention that maintaining that doc is the first order of business.
And for what it's worth, it's entry for Service is:
A twisted.application.service.Service [link to API doc]. See Application howto [link] for a description of how they relate to Applications [glossary link].
Superficially, this would appear to satisfy both you and Kevin: there is a glossary, and it is very explicit (at least in this entry) that the API doc is the canonical reference.
So whatever it is you're both asking for you perhaps both need to be clearer about what it is :)
I think that the fact such a discussion was able to go on for so long before we discovered it really just emphasizes another thing that comes up very frequently in these discussions: discoverability of the documentation. We need more and better links to such things.