Closed twisted-trac closed 19 years ago
twisted-trac
commented
20 years ago  |
@puzzlement commented |
|---|
#!html
<pre>
My current plan is: fix doc bugs, improve documentation when attention is drawn
to a particular doc (via a bug, probably).
People whining about documentation should be actively encouraged to file
documentation bugs and assign them to me.
</pre> |
@radix commented |
|---|
#!html
<pre>
We can talk about future ideas for docs here, and refer to other doc issues when
necessary.
It is assigned to hypatia as she has somewhat taken official responsibility as
the documentation editor.
</pre> |
@puzzlement commented |
|---|
#!html
<pre>
glyph's comments were:
- there isn't a good index.
- it's not sufficiently well-advertised which things are stable and
good, which things are unstable but worth trying out, and which are
dangerous and volatile experiments.
</pre> |
@radix commented |
|---|
#!html
<pre>
I think we need a series of "walkthroughs" that refer to existing docs (and fill
in the gaps with a paragraph or two of explanation on how the various bits go
together). Each walkthrough would be specifically for programmers who want to do
certain things: "Web Development" would be a big one. Also "Protocol
Implementation", "Deployment", and so on. (Hrmm, or maybe "Deployment" would be
at the end of each walkthrough, with considerations for each?)
</pre> |
@radix commented |
|---|
#!html
<pre>
I'm working on a mindmap of Twisted. A "Twisted Ontology", if you will, created
with FreeMind. I'm not sure how it will turn out, but I think it will be
interesting. I'll keep y'all updated.
</pre> |
@puzzlement commented |
|---|
#!html
<pre>
IRC discussion suggests:
- overview/tutorial on asynch programming
- better docs about Deferreds (related to the above?)
- better discussion of prerequisite knowledge for using Twisted/particular
parts of Twisted
- more discussion of what Twisted is (and indication that it isn't solely a web
server)
</pre> |
@puzzlement commented |
|---|
#!html
<pre>
moshez sent me a mail, the highlights are:
- re-order the docs, maybe slice up the tutorial and put bits of it in the
right places
- the components howto needs to be re-written (maybe around the tutorial?)
- address these FAQs better:
* How can I access self.factory from my Protocol's __init__?
* Where can I find out how to write Twisted servers?
* I get "Interrupted system call" errors when I use os.popen2. How do I read
results from a sub-process in Twisted?
* My Deferred or DeferredList never fires, so my program just mysteriously
hangs! What's wrong?
- fix the organisation of the Twisted Web docs: "configuration and programming
are documented together, while deployment strategies are discussed separately".
(I need to actually read the doc to figure out what a better arrangement is!)
- use Lore to add indices to docs
- fix Lore to invoke LaTeX index magic (people who know Lore can tell me if I
got it wrong and Lore does this already)
- document woven forms
moshez lists these bugs already filed -- 38, 261, 55, 375, 74, 153, 222, 88, 84,
89, 81, 53
</pre> |
@radix commented |
|---|
#!html
<pre>
note that the overview of async programming alreaddy exists:
http://twistedmatrix.com/documents/howto/async
Of course, improving it isn't a bad idea. And yes, putting some stuff about
Deferreds in there mightn't be a bad idea.
</pre> |
@puzzlement commented |
|---|
#!html
<pre>
My current priority list would be something like:
1. indicate "don't touch this! documented is not the same thing as
stable/good!" modules
2. redo the tutorial in some kind of sane way (waiting on definitions of sane,
in the meantime, I'll just chop it up and see if people think it's bad)
including linking from it to other docs
3. other stuff
What else needs to be done for 1? (I just DID Woven.)
</pre> |
spiv commented |
|---|
#!html
<pre>
[...]
>
> What else needs to be done for 1? (I just DID Woven.)
I just did a quick skim of the docs, and these all look like candidates for
1:
- row.xhtml
- dirdbm.xhtml
- im.xhtml
It turns out im already has a warning about being in a state of flux. I'm
not sure that row and dirdbm should fall into the "don't touch this!"
category, but as far as I'm aware they have very few users and the original
authors have moved on... Twisted has a very poor history when it comes to
persistence systems.
Does anyone care to comment on the current status of row and dirdbm?
-Andrew.
</pre> |
@puzzlement commented |
|---|
#!html
<pre>
Would it be worth having some kind of twisted.play module that sets up a lot of
the boilerplate currently used in the Deferred HOWTO (and probably elsewhere).
For example, reactor.callLater is used in the Deferred HOWTO all the time, and
the reader might be tempted to think that using it is a really common Twisted
idiom, whereas actually it's just a cheap way for us to set up the examples.
Would
deferred = twisted.play.DummyDeferred() be any better?
</pre> |
@radix commented |
|---|
#!html
<pre>
> Would it be worth having some kind of twisted.play module ...
Nah, I don't like the idea. *maybe*, if you *really* think it'd help,
you could just put something like this in the example:
def doSomethingAsynchronous():
"""
Simulate something asynchronous. See the
'Asynchronous Stuffs' in the Async howto for
more information.
"""
<whatever reactor.callLater stuff>
And the Async howto should explain how various different asynchronous
things can happen: via some library that already supports an API with
callbacks, or perhaps a transport.write() followed by a dataReceived()
.... etc
</pre> |
@puzzlement commented |
|---|
#!html
<pre>
> *maybe*, if you *really* think it'd help
You seem dubious about it being at all confusing. As someone whose familiarity
with async programming is at best tenuous, I'm willing to assure you that the
reactor.callLater stuff was in fact extremely confusing for me, because it looks
like an integral part of writing a twisted client (it happens in every example!)
when it is in fact not. I may be a particularly obtuse person, but then
documentation is often aimed at the lowest common denominator.
Your solution is probably adequate, if you accept that it will grow all the
examples by several lines.
</pre> |
spiv commented |
|---|
#!html
<pre>
Mary Gardiner added the comment:
>
> > *maybe*, if you *really* think it'd help
>
> You seem dubious about it being at all confusing. As someone whose familiarity
> with async programming is at best tenuous, I'm willing to assure you that the
> reactor.callLater stuff was in fact extremely confusing for me, because it looks
> like an integral part of writing a twisted client (it happens in every example!)
> when it is in fact not. I may be a particularly obtuse person, but then
> documentation is often aimed at the lowest common denominator.
Judging from the number of people I've seen on IRC confused by the Deferreds
howto, I'm inclined to agree with Mary.
The Deferreds howto currently suffers from the problem that there's two
distinct uses for deferreds: the callee's use, and the caller's. It's rare
for real code to need to care about both sides at once, but having complete,
self-contained examples requires that both sides are demonstrated at the
same time.
Perhaps there should be some terminology introduced to make this explicit --
the creator of a Deferred could be called the "manager" (a.k.a. the callee).
A Deferred manager is in charge of building deferreds, and arranging for
their callback/errback to be fired. On the other side, there's the "user"
(a.k.a. the caller). A Deferred user adds callbacks.
(Sometimes, a user will also return a Deferred to its caller, and so in some
sense is also a manager... hmm, this could still get confusing :/ )
Is the Deferred howto targetted at managers or users of Deferreds? At the
moment, I think it's aimed at both, and this probably needs to change.
Perhaps we should split "Deferred Execution" into a few seperate documents
like:
- Very very brief introduction
- "Using Deferreds"
- "Managing Deferreds"
- "Advanced" stuff -- DeferredList, maybeDeferred, the .debug flag, ...
The idea here is to try address the seperate audiences (of user and manager)
seperately, although trying to give complete, self-contained examples of
using deferreds without any managing of deferreds would be tricky :(
Maybe there could be a seperate "Deferreds by example" section after (or
before?) the "Using" and "Managing" sections...? It's much nicer when
relevant examples are embedded right in the discussion, though.
</pre> |
@glyph commented |
|---|
#!html
<pre>
Andrew Bennetts added the comment:
> - "Using Deferreds"
> - "Managing Deferreds"
> - "Advanced" stuff -- DeferredList, maybeDeferred, the .debug flag, ...
This absolutely clicks for me. I'd want to title them more verbosely
("Using interfaces which return Deferreds", "Creating request/response
clients and servers which use Deferreds", "Varieties of Deferred
Execution", "Dealing with asynchronous failure modes with Deferreds",
"Aggregating and manipulating Deferreds") but maybe that would just be
confusing. At any rate, this kind of breakdown would really help
newcomers understand what the reactor is.
</pre> |
@puzzlement commented |
|---|
#!html
<pre>
Glyph's titles sound more like subheadings or things that should go in the
introduction to me. The aim of an extended Deferred HOWTO for me (should I
author it) would be to aim it primarily at people unfamiliar with async style
programming, since that seems to be the background where the most questions come
from.
Perhaps a separate doc for people coming into this from an async background
would be in order?
There's a separate issue for this (504) which I created before this latest round
discussion began... I don't know roundup well enough to link the two.
</pre> |
@radix commented |
|---|
#!html
<pre>
this issue is long-unused; resolving.
</pre>
Searchable metadata
``` trac-id__397 397 type__enhancement enhancement reporter__radix radix priority__low low milestone__ branch__ branch_author__ status__closed closed resolution__fixed fixed component__ keywords__documentation documentation time__1068969170000000 1068969170000000 changetime__1100969402000000 1100969402000000 version__ owner__hypatia hypatia cc__glyph cc__radix cc__spiv cc__itamarst cc__hypatia ```