[Twisted-Python] Using SerialPort with t.a.s.Application

[Kevin Horn]

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 ;)

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.

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.

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.


> 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.)
- A succinct definition (like Itamar's quip above)
- a paragraph or two of discussion (not too long though!)
- "see also" links to HOWTO's etc.

I want to say that I do NOT think we should be trying to include every
single idea/concept/interface/class/whatever in whatever glossary comes up.
Just the main concepts.

Not to say that Itamar's answer to this particular question was incorrect or
> inappropriate, I just wouldn't want to see this enshrined as the official,
> central definition.
>
> 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, since we've gone to
> some trouble to make our jargon match the names used in code as closely as
> possible*.  In this case, <
> http://twistedmatrix.com/documents/10.2.0/api/twisted.application.service.IService.html>.
> If the API documentation is not sufficient (which in this case it may well
> not be), let's make the API documentation sufficient*.*  Don't fortify it
> with a redundant official glossary listing that has to be maintained in
> parallel and updated in synch with the API docs.
>

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?  And how often does someone show up on IRC who
doesn't understand what a Protocol object is show up?


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

Kevin Horn
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://twistedmatrix.com/pipermail/twisted-python/attachments/20110128/8c7390be/attachment.htm