[Twisted-Python] Task-based documentation started

[Glyph Lefkowitz]

On Jan 31, 2011, at 11:41 AM, Tom Davis wrote:

> Thoughts?


Priority #1 for most people who are enthusiastic about documentation is to come in and write a ton of additional documentation.  But this is a lot like trying to fix a large, broken, untested system by writing a pile of new, untested code, because "this time we'll get the design right".  What were the problems with the way the previous documentation got written?  How did we end up with this mess, and what is going to be done differently this time?  Most importantly, what is the metric by which we will judge this new documentation to be better?

If all that comes out of your efforts is a new, different pile of documentation, that's not entirely without value; different audiences understand things in different ways, so someone might pick it up and understand Twisted as a result.  But I very much doubt that's going to move us from a general impression of "bad docs" to a general impression of "good docs".

More specific criticism:

"This is a Twisted Task"?  I feel like I'm about to start reading about a Task object or something related to the twisted.internet.task module.  Or maybe that this is an exercise.  A document explaining how to do a task is rarely called a "task" itself.  Mostly they're called "How-To"s, actually.  I understand you're trying to get away from old terminology but this seems awkward and forced.
"You should be familiar with Resources"?  That is really broad and wide-ranging and should be a hyperlink to another tutorial.  Plus, I think that most people interested in these tasks will want to learn about how to get simple tasks done first, before moving on to a more abstract / theoretical understanding of the model behind them.  More importantly: this is a very wishy-washy definition of the audience.  Is it for system administrators?  Software developers?  DevOps people?  Graphic designers?  Power users?  What level of experience do they need with Python?  With networking?  With HTTP?
"Other configuration options are available"?  This should be a list of links to other documents that might help with some of those options.  Documentation which says "and then you could do something else" without telling you what else or why is needlessly confusing.
The WSGI example totally glosses over how you get your code onto sys.path (PYTHONPATH etc), says that 'helloworld' is a module/package (which is it?  why are both options given?).  This is an extremely confusing area for newbies, which is why it actually makes a bit of sense to me that the web-in-60-seconds WSGI tutorial starts with a callable defined in the .tac.  Not a good practice in the long term, but it allows the user to immediately get some feedback and have some notion of how things are wired together without having to debug Python's import system first.
.rpy scripts are for deployment, not debugging; I was a little concerned seeing that bullet point on the outline.  (See <http://twistedmatrix.com/documents/10.2.0/web/howto/web-in-60/rpy-scripts.html>.)

-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20110201/550f129d/attachment.html>