On 10:39 pm, tom@recursivedream.com wrote:

Take < http://twistedmatrix.com/documents/10.2.0/web/howto/web-in-60/static- content.html

...

:

Tell me the one command I need to serve a directory, *then* show me the code that one command effectively runs and vaguely what it does.

I think this is partially a disagreement over what tasks we actually want to document. If the command line interface gets primacy in the documentation, then I think you're writing documentation for end users (sys admins, non-programmers). I don't know about anyone else, but this category of documentation hadn't really crossed my mind before. I think that (ultimately) this is good documentation to have, but I don't know if it's as important as getting the programmer-oriented documentation in better shape. Another point to consider is that "twistd web" (and most other twistd plugins we provide) are semi-random mish mashes of functionality. They have accreted by contribution from many different people over the years with no governing design or goal aside from "expose features from the command line". This does not make them the friendliest tools around. The functionality they are missing is often surprising, particularly when contrasted with some of the (non-)functionality they do provide. I don't want to say that they do not bear documenting until their state is improved, but if we focused on other areas first, maybe we would have something better to document when we eventually get around to things like "twistd web". Jean-Paul

On Jan 31, 2011, at 3:19 PM, exarkun@twistedmatrix.com wrote:

On 10:39 pm, tom@recursivedream.com wrote:

...

Take < http://twistedmatrix.com/documents/10.2.0/web/howto/web-in-60/static- content.html

...

:

Tell me the one command I need to serve a directory, *then* show me the code that one command effectively runs and vaguely what it does.

I think this is partially a disagreement over what tasks we actually want to document. If the command line interface gets primacy in the documentation, then I think you're writing documentation for end users (sys admins, non-programmers). I don't know about anyone else, but this category of documentation hadn't really crossed my mind before.

Yes, and that's not good. We should be thinking about those people a little more :). Twisted is still mostly a library, but aside from my personal scheming to make it into something more, there's also the fact that users and sysadmins eventually need to interact with systems written using Twisted and there are basically no resources for them to learn to manage said systems. As much controversy as there is over exactly how good or bad our docs are, I think we can all agree that admin/user docs are in much worse shape than our developer docs (i.e. they are non-existant) :). But more importantly...

I think that (ultimately) this is good documentation to have, but I don't know if it's as important as getting the programmer-oriented documentation in better shape.

I think that this is actually a better way to deal with most of our programmer-focused documentation. Most importantly, the first rule here is very important: <http://jacobian.org/writing/great-documentation/what-to-write/>. "Be quick.". Good documentation writers frequently stress the importance of immediate gratification. Good game designers will also tell you that you want to get a user engaged and experiencing success during the tutorial, before they really know how to play the game. The immediate dopamine hit from a working 'twistd' command-line will carry the user through the slightly more confusing parts of getting their own code to work: it assures them that they can get Twisted to do _something_, which gives them immediate hope that maybe one day they can get Twisted to do what they want. A corollary to this is that if it's going to fail, it can fail faster, and we all know that one should fail as fast as possible. If the 'twistd' command-line doesn't even work, that lets the tutorial reader address configuration and installation issues much earlier on, rather than try to debug them as issues with their own code, they can just say, 'I ran this command and I got a traceback', which will get the attention of a Twisted maintainer more quickly because it's easier to diagnose something that's purely under our own control than a (potentially arbitrary, even if small) pile of new code. I actually think that the inclusion of the 'twistd web' command-lines is one of the things that made the web-in-60-seconds tutorial series a big improvement over our previous web documentation :).

Another point to consider is that "twistd web" (and most other twistd plugins we provide) are semi-random mish mashes of functionality. They have accreted by contribution from many different people over the years with no governing design or goal aside from "expose features from the command line". This does not make them the friendliest tools around. The functionality they are missing is often surprising, particularly when contrasted with some of the (non-)functionality they do provide.

No argument here. Le sigh.

I don't want to say that they do not bear documenting until their state is improved, but if we focused on other areas first, maybe we would have something better to document when we eventually get around to things like "twistd web".

I _want_ people to show up on the tracker and actually report usability issues and missing functionality from the command-line tools. It's still surprising to a lot of people, even very experienced twisted people, just how much functionality is exposed by those tools. And if nobody knows the tools are there, then chances are they will remain a non-priority forever, as functional library issues will continue to get reported by the much wider audience that's actually using them. Plus, on the bright side, the increasing prevalence of the use of cred and endpoint string-plugin APIs means that some of the twistd plugins are starting to become actually useful for things where they weren't before. 'twistd' web, in particular, also has RPYs, which almost turn it into a full-featured server; other servers should have similar application-level plugins. (And as I finish writing this, I think: 'twistd web' could be _really_ pretty useful if it weren't such a pain to deploy a WSGI app using an RPY, thanks to threadpools etc. We should add a utility function or something. Anybody feel like writing a ticket? I have heard references to '.wsgi' files, is that a thing we could support?)

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

Thoughts?

Overall I think the layout and structure is a big improvement over the current Twisted documentation. It's easier to navigate and grok where you want to go. While the content of the web tutorial is thin, I think Jean-Paul's Twisted Web in 60 seconds adapted to that style and layout would help a lot. This documentation looks the part, which is something Twisted really needs. -J

On Tue, Feb 1, 2011 at 3:44 AM, Albert Brandl <albert.brandl@weiermayer.com>wrote:

On Mon, Jan 31, 2011 at 02:41:38PM -0500, Tom Davis wrote:

...

Thoughts?

I think that the overview in the first two sections is very good. It made me curious to learn more.

The "breadcrumbs" on the main page look like this: "Contents :: Serving on the Web — HTML, CGI, WSGI, etc. » " Might be a problem with the Sphinx configuration.

Yeah, this is just how the Sphinx template lays things out and it's the default one I use for documentation on my site, merely because the color scheme is similar. It's definitely not the greatest and a Twisted-theme one already exists so we'll be working from that.

Not sure about the link "read more about Twisted": There _is_ more about Twisted on the rest of the page. When I clicked the link, I expected to be redirected to twistedmatrix.com or something like this. Maybe you don't need a link at this position at all.

Well, that was originally going to lead to some history/about stuff, but looking at it again that doesn't seem like an initially great use of time.

In the "Why Use Twisted" section, you write "Framework" - not sure if this should be uppercased. But there are some other nouns (Tasks, Project Documentation) that are written this way, so maybe it's Your Way Of Emphasizing Things ;-).

I'm also not sure if the explanation why I would use Twisted should be in bold letters. Everywhere else you use italics.

Do you intend to create a task description for connecting to an SSH server (maybe with certificates)? This is something that whould have been handy for me in the past.

Either create or expose one that already exists, yes.

The "Everything Else" section should not contain links that are already presented somewhere else.

These are ToC trees which are different from inline links. I don't feel there's much harm in linking to something twice on one page especially when the same words are used and one of the uses is clearly a ToC.

Do you intend to add some links to external pages here (e.g. the API documentation or other web pages describing how to use the framework)? Or should this documentation be self-contained?

API links will be common and will be under some reference/links area, I'm sure. It is very much a work in progress.

One small usability quirk: The presentation of links in an orange, bold font does not have much recognition value. I think it would be better to use the standard way of marking links by using a blue, underlined font. The same goes for links that have already been visited.

Again, this is a Sphinx template issue so we'll see how it changes with the actual Twisted one :) Thanks for the feedback! -Tom

Best regards,

Albert -- Albert Brandl Weiermayer Solutions GmbH | Abteistraße 12, A-4813 Altmünster phone: +43 (0) 720 70 30 14 | fax: +43 (0) 7612 20 3 56 web: http://www.weiermayer.com

_______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

On Feb 1, 2011, at 10:53 AM, Tom Davis wrote:

On Tue, Feb 1, 2011 at 12:58 PM, Glyph Lefkowitz <glyph@twistedmatrix.com> wrote:

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?

I'm still really interested in concise answer to that last question there. What are the priorities for what you're trying to improve? What you've listed here is "the steps you're going to take in order to improve it" but I have yet to see a lucid description of the problem in detail.

Those tutorials aren't new at all; they were taken (often verbatim) from the "using twisted.web" document. Writing a ton of new documentation really isn't my goal at all. My goals are threefold: Reorganize existing documentation in a way that makes it more accessible. Accessible to whom? How will reorganizing it make it more accessible? One way to interpret this statement is that your goal is to remove all diagrams, because the documentation is currently not accessible to the blind. I'm pretty sure that's not what you mean, but it's a good example of how ambiguous this statement is :). (Plus, the couple of blind developers I've talked to about Twisted didn't seem to have a problem with the docs...) Edit existing documentation to conform to a task (howto/tutorial/etc.) vs. expanded learning model. (the whole instant gratification thing and all that) OK, I'm on board with that. Except that in order to understand the tutorial documentation you need a good backing of reference docs, so it's not like you can just choose one over the other. And we have lots of tutorial docs (c.f. the infamous finger tutorial) which are in the tutorial / task-oriented paradigm but don't teach much that's directly useful. Gradually update / replace code listings with "current best practices" examples that are tested. No arguing with that at all, that sounds great.

I know you want an actual *layout* for the reorganization.

Not really. What I want is a clear understanding of what you intend to change. I usually get that by reading a diff: it's easy to read a diff and see what changed in the old versus the new version of something. I can tell if it's an improvement without having to digest the entire content. But the structure of <http://docs.recursivedream.com/twisted/> is a sprawling mess of placeholders and half-finished ideas. It's different from the existing documentation in lots of ways; it has a completely different stylesheet (which I assume is some standard Sphinx thing we will get rid of with the consistent theming work in Kevin's sphinx transition). I don't know what I'm looking at or how to appreciate it. This is why I started off by complaining about the separate git repository. If you're going to work in a separate repository and a separate format and not produce diffs that I can skim, then it's very hard to comment intelligently on your strategy, and you need to take an immense amount of care to call out the sections you consider complete, what exactly you want feedback on, and areas where you have or haven't added new content (so you can't be blamed for issues in old content that you're not trying to update). Note that diffs against Kevin's sphinx output would basically satisfy this same requirement, even if that output isn't really complete and those diffs would need to be re-created when the final conversion occurred. At least there would be a set of deltas to look at rather than a whole new structure which is mostly scaffolding.

I want to give that to you, but it requires going through all the documentation and making sure it fits in the reorganized layout or making sections for it when it doesn't which is far more time consuming than providing a layout for the "task" piece, as I did here. I'm basically just saying "How-tos should have a standard layout with these sections; here's a stub of one such how-to as incompletely adapted from the current documentation".

Even going back and reading your original message to this thread now, I can't tell that this is what you were asking for review of. Even now I'm not entirely sure what you mean. Do you mean that you want feedback on the sections on <http://docs.recursivedream.com/twisted/projects/web/tasks/serve/index.html>? Or the way that <http://docs.recursivedream.com/twisted/projects/web/tasks/serve/serve.html> is split out into separate tasks? If you are interested in getting a review of the template or the outline, please write up the template itself with a description of what should go into each section. Then you could link from the template to web/tasks/serve/index and say "and here's an example of some existing documentation applied to this outline". But since I have no idea what the generic purpose of each section is, I can't comment on whether the sections are a bad idea or the classifications of certain sections of existing docs is a bad idea or if it's just too incomplete for me to comment on. Plus, such a template would serve as a critical tool for new documentation authors (of which I hope we get a few), allowing for a consistent style to be followed by multiple authors writing task-oriented documentation for different parts of Twisted. The lack of such meta-documentation is the root of many issues with the current docs: when we're writing code for Twisted, we have a very clear idea of what the coding standards are, but when we approach documentation, the individual author just writes whatever random style happens to suit them on that day. There's no guidance.

I think most of this is a huge misunderstanding as to my goals both in general and for the particular section critiqued here. Perhaps I should have completed it before putting it up for review. I just felt it was better to get something out here just in case everybody hated the entire direction rather than spend a ton of time slicing the current web server docs the way I personally feel they should fit together in order to properly serve the audience.

Soliciting feedback is good. I still think that these discussions have been very productive. The issue I have isn't that it's unfinished, it's that there are no guard-rails on the unfinished sections, so it's easy to careen off into the stuff that I'm not really supposed to be paying attention to. A substantially larger document with that same problem would have been a disaster to try to review, so early feedback is better; hopefully as you produce something bigger you'll also alleviate the difficulty of review somehow.

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. I just started using this terminology because it seemed common within our conversations. How-to/tutorial would likely be less confusing.

OK. For what it's worth I share your desire for a new / better term but I can't think of one.

"You should be familiar with Resources"? That is really broad and wide-ranging and should be a hyperlink to another tutorial. It was just a placeholder; it should link to a section in the web server overview docs that talks about Resources. There are other things on that list, too (Site object, yada yada). Although, like I said, it's merely incomplete.

I suppose my comments above about meta-documentation and a deeper explanation of the template are my response to this; if it were clearer what the structure were really supposed to be representing it would be easier to ignore minor flaws like this or recommend improvements

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. I completely agree. That's my whole point with starting off using *twistd*, despite its limitations or whatever.

Obviously from my other message I'm a fan of this approach.

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? The latter should all be under "Prerequisites" whereas "audience" should probably be a new howto standard section that's currently overlooked (perhaps above "Prerequisites"?)

It seems to me that "audience" is the section and "prerequisites" should be a sub-section of that. After all prerequisites are really attributes of the audience, not the document :).

"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. I agree. There are lots and lots of lines to connect even from such a simplistic tutorial. I wanted to get feedback on the layout rather than the final web project documentation which should certainly include links to twistd option docs and probably a half dozen other things I haven't linked to yet.

(Again, go write up the layout explicitly first, and then I can provide more useful feedback!)

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. Fair enough. This point was also not covered in the official docs, where I got the instructions from. Regardless, I have no intention of including how-tos that gloss over anything; either they work "out of the box" or are edited until they do.

I guess this is another nitpick that wasn't really about the layout. Sounds like we feel the same way, at any rate.

.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.ht...>.) Huh? The docs you link to claim:

So, while rpy scripts may be useful for testing out ideas, they're not recommend for much more than that.

Am I missing something here?

Well, "testing out" and "debugging" aren't quite the same thing. And I'd probably recommend RPYs for more than that :). I was linking to that document just to provide an expanded explanation of the functionality; personally I find it obvious why RPYs are super useful from that example, so I mostly just ignore that comment. (Perhaps this doc needs to be updated, but let's please not hijack this already-sprawling thread for discussion of the merits and flaws of RPYs...)

My hope is that this reply clears up some confusion. However, feel free to let me know if you think I simply don't have the mindset necessary to "improve" the documentation in a way that is desirable. I had a hard time learning Twisted in the beginning and to this day some really helpful abstractions and just available projects / solved problems elude me.

This sounds like I'm discouraging you. If that's the case, feel free to just tell me to sit this one out and wait until you're further along in the project. I am trying to provide feedback to be useful to your efforts, but if you don't find it useful, then you can carry on with feedback from people who really need the docs.

I think the reason for this is that I think a lot like Jacob <http://jacobian.org/writing/great-documentation/> when it comes to documentation and that's the sort of stuff I need to have in order to truly grok something. Maybe that's what we all want here. Maybe it isn't, though. And I'd really love to figure out which it is before I drive forward on this. If we really are on the same page (and I'd certainly like to be), we've got some hellish communication issues ;)

I'm a big fan of Jacob's in general and that essay series in particular as far as it comes to documentation, so I don't think that's the issue. Obviously his methods have yielded a result that is well-regarded in the Django community. And I think we are on the same page about many things, and we don't need to agree about everything. I'm still quite excited to have you working on our documentation. (Except for his comment about API documentation generators; I think that epydoc/pydoc is hugely useful. But I do agree that one shouldn't just run an auto-generator to spit out a rehash of the source code; one needs to write a ton of documentation in an appropriate format to be consumed by such a tool in order for it to be useful.) Thanks and good luck, -glyph

On Tue, Feb 1, 2011 at 5:15 PM, Glyph Lefkowitz <glyph@twistedmatrix.com>wrote:

On Feb 1, 2011, at 10:53 AM, Tom Davis wrote:

On Tue, Feb 1, 2011 at 12:58 PM, Glyph Lefkowitz <glyph@twistedmatrix.com>wrote:

...

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?*

I'm still really interested in concise answer to that last question there. What are the priorities for what you're trying to improve? What you've listed here is "the steps you're going to take in order to improve it" but I have yet to see a lucid description of the problem in detail.

I think the problem is largely one of organization (as it relates to "accessibility", e.g. how / under what context do I get linked to such and such thing?) and outdated documentation. I think the individual problems are all very well-known and while there is not some overarching problem with all the documentation that requires starting from scratch, reorganizing and restructuring what's there may make it look like I'm trying to do that.

Those tutorials aren't new at all; they were taken (often verbatim) from the "using twisted.web" document. Writing a ton of new documentation really isn't my goal at all. My goals are threefold:

1. Reorganize existing documentation in a way that makes it more accessible.

Accessible to whom? How will reorganizing it make it more accessible? One way to interpret this statement is that your goal is to remove all diagrams, because the documentation is currently not accessible to the blind. I'm pretty sure *that's* not what you mean, but it's a good example of how ambiguous this statement is :). (Plus, the couple of blind developers I've talked to about Twisted didn't seem to have a problem with the docs...)

1. Edit existing documentation to conform to a task (howto/tutorial/etc.) vs. expanded learning model. (the whole instant gratification thing and all that)

OK, I'm on board with that. Except that in order to understand the tutorial documentation you need a good backing of reference docs, so it's not like you can just choose one over the other. And we have lots of tutorial docs (c.f. the infamous finger tutorial) which are in the tutorial / task-oriented paradigm but don't teach much that's directly useful.

Finger is a really bad example of what a howto should be; it doesn't teach you how to achieve some specific, common goal quickly and easily. The names howto <http://twistedmatrix.com/documents/current/names/howto/names.html>is a good example of a howto that tells me exactly how to do something in as few steps as humanly possible. It could use a reference to wherever all the functions (SOA, A, NS, etc.) are coming from and links to some follow-up documentation of the *names* project in general, but I digress.

1. Gradually update / replace code listings with "current best practices" examples that are tested.

No arguing with that at all, that sounds great.

I know you want an actual *layout* for the reorganization.

Not really.

What I want is a clear understanding of what you intend to change. I usually get that by reading a diff: it's easy to read a diff and see what changed in the old versus the new version of something. I can tell if it's an improvement without having to digest the entire content.

But the structure of <http://docs.recursivedream.com/twisted/> is a sprawling mess of placeholders and half-finished ideas. It's different from the existing documentation in lots of ways; it has a completely different stylesheet (which I assume is some standard Sphinx thing we will get rid of with the consistent theming work in Kevin's sphinx transition). I don't know what I'm looking at or how to appreciate it.

This is why I started off by complaining about the separate git repository. If you're going to work in a separate repository and a separate format and not produce diffs that I can skim, then it's *very* hard to comment intelligently on your strategy, and you need to take an immense amount of care to call out the sections you consider complete, what exactly you want feedback on, and areas where you have or haven't added new content (so you can't be blamed for issues in old content that you're not trying to update).

Note that diffs against Kevin's sphinx output would basically satisfy this same requirement, even if that output isn't really complete and those diffs would need to be re-created when the final conversion occurred. At least there would be a set of deltas to look at rather than a whole new structure which is mostly scaffolding.

I'm just going to start making diffs against Kevin's lore2sphinx output as suggested. He's given me instructions on how to generate the docs and I'll attempt to create specific patches and tickets against that output to the extent possible. My hope is that this method will allow the project to get somewhere that doesn't result in me ending up with a bunch of third-party Twisted documentation because nobody could ever really agree on why it was an improvement in the first place. And on that note, perhaps it won't be an objective improvement. I'm open to the possibility that the documentation is sufficient for most people and I'm just an exception to that—or that my "improvements" are only really helpful to me. But I'm certainly going to keep looking for ways to suitably prove the general case, for everybody's benefit; I have no desire to end up with something that only benefits me.

I want to give that to you, but it requires going through all the documentation and making sure it fits in the reorganized layout or making sections for it when it doesn't which is far more time consuming than providing a layout for the "task" piece, as I did here. I'm basically just saying "How-tos should have a standard layout with these sections; here's a stub of one such how-to as incompletely adapted from the current documentation".

Even going back and reading your original message to this thread now, I can't tell that this is what you were asking for review of. Even now I'm not entirely sure what you mean. Do you mean that you want feedback on the sections on < http://docs.recursivedream.com/twisted/projects/web/tasks/serve/index.html>? Or the way that < http://docs.recursivedream.com/twisted/projects/web/tasks/serve/serve.html> is split out into separate tasks?

If you are interested in getting a review of the template or the outline, please write up the template itself with a description of what should go into each section. Then you could link from the template to web/tasks/serve/index and say "and here's an example of some existing documentation applied to this outline". But since I have no idea what the generic purpose of each section is, I can't comment on whether the sections are a bad idea or the classifications of certain sections of existing docs is a bad idea or if it's just too incomplete for me to comment on.

Plus, such a template would serve as a critical tool for new documentation authors (of which I hope we get a few), allowing for a consistent style to be followed by multiple authors writing task-oriented documentation for different parts of Twisted. The lack of such meta-documentation is the root of many issues with the current docs: when we're writing code for Twisted, we have a very clear idea of what the coding standards are, but when we approach documentation, the individual author just writes whatever random style happens to suit them on that day. There's no guidance.

I think most of this is a huge misunderstanding as to my goals both in general and for the particular section critiqued here. Perhaps I should have completed it before putting it up for review. I just felt it was better to get *something* out here just in case everybody hated the entire direction rather than spend a ton of time slicing the current web server docs the way I personally feel they should fit together in order to properly serve the audience.

Soliciting feedback is good. I still think that these discussions have been very productive. The issue I have isn't that it's unfinished, it's that there are no guard-rails on the unfinished sections, so it's easy to careen off into the stuff that I'm not really supposed to be paying attention to. A substantially larger document with that same problem would have been a disaster to try to review, so early feedback is better; hopefully as you produce something bigger you'll also alleviate the difficulty of review somehow.

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.

I just started using this terminology because it seemed common within our conversations. How-to/tutorial would likely be less confusing.

OK. For what it's worth I share your desire for a new / better term but I can't think of one.

...

- "You should be familiar with Resources"? That is really broad and wide-ranging and should be a hyperlink to another tutorial.

It was just a placeholder; it should link to a section in the web server overview docs that talks about Resources. There are other things on that list, too (Site object, yada yada). Although, like I said, it's merely incomplete.

I suppose my comments above about meta-documentation and a deeper explanation of the template are my response to this; if it were clearer what the structure were really supposed to be representing it would be easier to ignore minor flaws like this or recommend improvements

...

- 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.

I completely agree. That's my whole point with starting off using *twistd*, despite its limitations or whatever.

Obviously from my other message I'm a fan of this approach.

...

- 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?

The latter should all be under "Prerequisites" whereas "audience" should probably be a new howto standard section that's currently overlooked (perhaps above "Prerequisites"?)

It seems to me that "audience" is the section and "prerequisites" should be a sub-section of that. After all prerequisites are really attributes of the audience, not the document :).

...

- "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.

I agree. There are lots and lots of lines to connect even from such a simplistic tutorial. I wanted to get feedback on the *layout* rather than the final web project documentation which should certainly include links to twistd option docs and probably a half dozen other things I haven't linked to yet.

(Again, go write up the layout explicitly first, and then I can provide more useful feedback!)

...

- 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.

Fair enough. This point was also not covered in the official docs, where I got the instructions from. Regardless, I have no intention of including how-tos that gloss over *anything; *either they work "out of the box" or are edited until they do.

I guess this is another nitpick that wasn't really about the layout. Sounds like we feel the same way, at any rate.

...

- .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.ht...

...

.)

Huh? The docs you link to claim:

So, while rpy scripts may be useful for testing out ideas, they're not

...

recommend for much more than that.

Am I missing something here?

Well, "testing out" and "debugging" aren't quite the same thing. And I'd probably recommend RPYs for more than that :). I was linking to that document just to provide an expanded explanation of the functionality; personally I find it obvious why RPYs are super useful from that example, so I mostly just ignore that comment. (Perhaps this doc needs to be updated, but let's please not hijack this already-sprawling thread for discussion of the merits and flaws of RPYs...)

My hope is that this reply clears up some confusion. However, feel free to let me know if you think I simply don't have the mindset necessary to "improve" the documentation in a way that is desirable. I had a hard time learning Twisted in the beginning and to this day some really helpful abstractions and just available projects / solved problems elude me.

This sounds like I'm discouraging you. If that's the case, feel free to just tell me to sit this one out and wait until you're further along in the project. I am trying to provide feedback to be useful to your efforts, but if you don't find it useful, then you can carry on with feedback from people who really need the docs.

I think the reason for this is that I think a lot like Jacob < http://jacobian.org/writing/great-documentation/> when it comes to documentation and that's the sort of stuff I need to have in order to truly grok something. Maybe that's what we all want here. Maybe it isn't, though. And I'd really love to figure out which it is before I drive forward on this. If we really are on the same page (and I'd certainly like to be), we've got some hellish communication issues ;)

I'm a big fan of Jacob's in general and that essay series in particular as far as it comes to documentation, so I don't think that's the issue. Obviously his methods have yielded a result that is well-regarded in the Django community. And I think we are on the same page about many things, and we don't *need* to agree about everything.

I'm still quite excited to have you working on our documentation.

(Except for his comment about API documentation generators; I think that epydoc/pydoc is hugely useful. But I do agree that one shouldn't just run an auto-generator to spit out a rehash of the source code; one needs to write a ton of documentation in an appropriate format to be consumed by such a tool in order for it to be useful.)

Thanks and good luck,

-glyph

_______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python