On Jan 29, 2011, at 10:47 PM, Andrew Bennetts <and...@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. _______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
