<div class="gmail_quote">On Sun, Jan 30, 2011 at 2:22 AM, Glyph Lefkowitz <span dir="ltr"><<a href="mailto:glyph@twistedmatrix.com">glyph@twistedmatrix.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
<div class="im">On Jan 29, 2011, at 10:47 PM, Andrew Bennetts <<a href="mailto:andrew@bemusement.org">andrew@bemusement.org</a>> wrote:<br>
<br>
> Glyph Lefkowitz wrote:<br>
> [...]<br>
>> The whole idea of a glossary concerns me a little bit. … However, Twisted<br>
>> does have its own jargon and a dictionary to help the novice parse it would<br>
>> be a good thing.<br>
>> What I'd really like to see in this regard is to make sure that every<br>
>> "jargon term" is linked straight to API documentation<br>
><br>
> We already have a glossary:<br>
><br>
> <<a href="http://twistedmatrix.com/documents/current/core/howto/glossary.html" target="_blank">http://twistedmatrix.com/documents/current/core/howto/glossary.html</a>><br>
<br>
</div>Yeah, that came up a bit later in the thread :). And kevin did mention that maintaining that doc is the first order of business.<br>
<div class="im"><br>
> And for what it's worth, it's entry for Service is:<br>
><br>
> A twisted.application.service.Service [link to API doc]. See<br>
> Application howto [link] for a description of how they relate to<br>
> Applications [glossary link].<br>
><br>
> Superficially, this would appear to satisfy both you and Kevin: there is<br>
> a glossary, and it is very explicit (at least in this entry) that the<br>
> API doc is the canonical reference.<br>
><br>
> So whatever it is you're both asking for you perhaps both need to be<br>
> clearer about what it is :)<br>
<br>
</div>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.<br>
<div><div></div><br></div></blockquote></div><br>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.<br>
<br>Secondly, Twisted actually has 2 glossaries. One general one (referenced above) and one specific to Twisted Web (here: <a href="http://twistedmatrix.com/documents/current/web/howto/glossary.html">http://twistedmatrix.com/documents/current/web/howto/glossary.html</a>). It has, however, only one entry. I intend in future to combine the two, unless someone else does it first.<br>
<br>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.<br>
<br>Should help quite a bit, I think. <br><br>Kevin Horn<br><br>(*) I know, I _know_! I'm working on it! :)<br><br>