On Sun, Jan 30, 2011 at 2:22 AM, Glyph Lefkowitz <gl...@twistedmatrix.com>wrote:
> 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. > > 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! :)
_______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
