On Jan 29, 2011, at 10:47 PM, Andrew Bennetts <andrew@bemusement.org> wrote:Yeah, that came up a bit later in the thread :). And kevin did mention that maintaining that doc is the first order of business.
> 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>
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.
> 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 :)