On Sun, Jan 30, 2011 at 2:22 AM, Glyph Lefkowitz <glyph@twistedmatrix.com>wrote:
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.
Well, first off, I did know about the glossary. It's dismal state is one of the things that motivated me to start working on Twisted Documentation. As I mentioned in the other thread, a glossary is one of the first things I look for in a documentation set. Secondly, Twisted actually has 2 glossaries. One general one (referenced above) and one specific to Twisted Web (here: http://twistedmatrix.com/documents/current/web/howto/glossary.html). It has, however, only one entry. I intend in future to combine the two, unless someone else does it first. Thirdly, as far as discoverability/navigability of the documentation, I think Sphinx (*) will help a lot here. It has all kinds of tools to make cross-linking as easy as possible, like the toc segments in the sidebar, prev/next links, glossary links, indexing, etc. Should help quite a bit, I think. Kevin Horn (*) I know, I _know_! I'm working on it! :)