[Twisted-Python] Using SerialPort with t.a.s.Application

[Glyph Lefkowitz]

On Jan 29, 2011, at 10:47 PM, Andrew Bennetts <andrew at 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.