[Twisted-Python] glossary (was Re: Using SerialPort with t.a.s.Application)

[Glyph Lefkowitz]

On Jan 28, 2011, at 5:47 PM, Kevin Horn wrote:

> 
> 
> On Fri, Jan 28, 2011 at 1:33 PM, Glyph Lefkowitz <glyph at twistedmatrix.com> wrote:
> 
> On Jan 28, 2011, at 10:38 AM, Kevin Horn wrote:
> 
>> 
>> 
>> On Fri, Jan 28, 2011 at 7:25 AM, Itamar Turner-Trauring <itamar at itamarst.org> wrote:
>> 
>> A service is supposed
>> to be something you can start and stop, and encapsulates a
>> self-contained piece of business logic.
>> 
>> -Itamar
>> 
>> 
>> 
>> This or something very much like it should be in the Twisted Glossary.
>> 
>> Kevin Horn 
> 
> The whole idea of a glossary concerns me a little bit.  
> 
> You're just saying that because you don't want anyone else to understand what you're saying ;)

I am aggrieved that you would insinuate any premeditated obfuscatory animus appertaining to my person or those of my associates.  I maintain an amaranthine focus on limpid exposition and efficacious intercommunication.

> Seriously though.  When I first started thinking about ways to improve the documentation.  The _first_ thing I thought was missing was decent explanations of some of these things.  Whether it's in a glossary or someplace else, clear definitions need to exist for all the major Twisted concepts (people may disagree on what is or is not major, and that's fine).  Putting these definitions (or links to them) in a glossary keeps them all together and easy to find and refer to.  One of the first thing I look for in any software documentation is a glossary or some set of definitions that I can refer to while I'm _reading_ the API docs or whatever.

If you need a glossary open while you're reading the API docs, that means that the docs you're reading are insufficiently marked up.  The word 'service' (in this context) should _always_ itself be a hyperlink to the IService interface.  We do this pretty consistently in all new documentation.  Similarly 'deferred' should always be a link to twisted.internet.defer.Deferred.  <http://epydoc.sourceforge.net/epytext.html> has more detail on how to format these if you want to do clever stuff like have a lower-case word like 'service' link to the IService docs.

I'm totally on board with making a list of these common abstractions outside the API docs, but 99% of what that list should do is provide a definitive index of links into the API docs to call out the top important interfaces you need to read about.

Also, the existing API docs for many of the core concepts are terrible, or even (cringe) non-existent in places, so they could certainly stand to be improved.  I'm not saying our existing docs are great, just that we should have one great index of terms and not five mediocre ones.

> Solving problems through software requires finding the right abstractions, which IMO depends a great deal on finding the right vocabulary for those abstractions.  I know the Twisted devs spend a lot of time and energy trying to find exactly the right word for a class, or a method, or whatever.  Let's communicate that to new people!  If you don't want a "glossary", then we'll do something else, but I think it's important to have all of the really critical concepts described in one place somewhere.

I should have qualified my discomfort with the term 'glossary' a bit more.  We do need the thing you're talking about.  My only concern is redundancy.  Even if we had awesome API documentation for all of these things, there's still a bootstrapping phase where people are not sure which classes are one-off utilities and which things are core abstractions they'll be using every day.

> Also consider the problem of reverse human lookup:  "Oh man, what was that thing called that stops and starts Twisted code at the appropriate times?"
> 
> If you stick that into a search engine, you probably won't find it for a loooong time.  But if there's a glossary, you just look there, and you find it pretty easily.

Well, that exact phrase, no; but "start and stop twisted application", and "start and stop twisted service" both point at the right API doc.  We should probably work a bit harder to make 'start stop twisted' find that page first :).

> One way I frequently see it done is vague little snippets of text like this, and I don't like that.  
> 
> Well, I consider it much more meaningful than what is currently there.  Not saying it's really sufficient, but it is succinct.  I think what I'd like to see is a "glossary" entry with:
> 
> - an API link (e.g. "An object which implements the IService Interface" -- and yes, it should be a proper English sentence.)

This I certainly agree with.

> - A succinct definition (like Itamar's quip above)
> - a paragraph or two of discussion (not too long though!)

Why can't this just be in the API doc?

> - "see also" links to HOWTO's etc.

Again - why not in the API doc?  If someone were to find the concept via some other documentation that described the term in question as a return type or argument rather than a generic word, presumably that person might also want to read the narrative documentation.

> I'm not sure how much of a problem maintaining it would be, especially as I agree that linking to the API docs is probably a good idea (though I think a lot of the docstrings in there could be greatly improved).  For one thing, how often has the _intent_ of the IProtocol interface(which has no docstring, btw) changed?

So, first: aaaaaauuugh.  Is there a doc bug for that?  That is an interface which really, really needs a docstring.  Can you submit a patch, like, right now? :)

Second: the intent hasn't changed often.  But clearly we need to update the documentation to document that intent better, and I hope that happens more often than it does.  Narrative vs. reference documentation is already a split, albeit a necessary one in my opinion.  Narrative vs. code-reference vs. language-reference seems like we're just splitting hairs.

> And how often does someone show up on IRC who doesn't understand what a Protocol object is show up?

Actually... I don't remember IProtocol being a big problem.  Which is slightly surprising, given that it has no docstring.  Maybe everyone who has run into a confusion at this basic stage has just given up, or maybe the method docstrings are good enough, or maybe the learn about it from a tutorial.

> Thoughts?
> 
> 
> I think we've totally hijacked this thread :)

Yes, retitled appropriately.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://twistedmatrix.com/pipermail/twisted-python/attachments/20110128/1fa2ffbb/attachment-0001.htm