<div class="gmail_quote">On Tue, Feb 1, 2011 at 12:58 PM, Glyph Lefkowitz <span dir="ltr"><<a href="mailto:glyph@twistedmatrix.com">glyph@twistedmatrix.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<div style="word-wrap:break-word"><div class="im"><br><div><div>On Jan 31, 2011, at 11:41 AM, Tom Davis wrote:</div><br><blockquote type="cite"><span style="border-collapse:separate;font-family:'Bitstream Vera Sans Mono';font-style:normal;font-variant:normal;font-weight:normal;letter-spacing:normal;line-height:normal;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px;font-size:medium"><div>
Thoughts?</div></span></blockquote></div><div><br></div></div><div>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, <i>what is the metric by which we will judge this new documentation to be <b>better</b>?</i></div>
</div></blockquote><div><br></div><div>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:</div>
<div><ol><li>Reorganize existing documentation in a way that makes it more accessible.</li><li>Edit existing documentation to conform to a task (howto/tutorial/etc.) vs. expanded learning model. (the whole instant gratification thing and all that)</li>
<li>Gradually update / replace code listings with "current best practices" examples that are tested.</li></ol></div><div>I know you want an actual *layout* for the reorganization. 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".</div>
<div><br></div><div>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 <i>something</i> 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.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;"><div style="word-wrap:break-word"><div><br></div><div>If all that comes out of your efforts is a new, different pile of documentation, that's not <i>entirely</i> 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".</div>
<div><br></div><div>More specific criticism:</div><div><br></div><div><ul><li>"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.</li>
</ul></div></div></blockquote><div>I just started using this terminology because it seemed common within our conversations. How-to/tutorial would likely be less confusing.</div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<div style="word-wrap:break-word"><div><ul><li>"You should be familiar with Resources"? That is really broad and wide-ranging and should be a hyperlink to another tutorial.</li></ul></div></div></blockquote><div>
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.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;"><div style="word-wrap:break-word"><div><ul><li> 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.</li>
</ul></div></div></blockquote><div>I completely agree. That's my whole point with starting off using *twistd*, despite its limitations or whatever. </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<div style="word-wrap:break-word"><div><ul><li>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?</li>
</ul></div></div></blockquote><div>The latter should all be under "Prerequisites" whereas "audience" should probably be a new howto standard section that's currently overlooked (perhaps above "Prerequisites"?)</div>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;"><div style="word-wrap:break-word"><div><ul><li>"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.</li>
</ul></div></div></blockquote><div>I agree. There are lots and lots of lines to connect even from such a simplistic tutorial. I wanted to get feedback on the <i>layout</i> 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. </div>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;"><div style="word-wrap:break-word"><div><ul><li>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 <i>extremely</i> 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.</li>
</ul></div></div></blockquote><div>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 <i>anything; </i>either they work "out of the box" or are edited until they do.</div>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;"><div style="word-wrap:break-word"><div><ul><li>.rpy scripts are for deployment, not debugging; I was a little concerned seeing that bullet point on the outline. (See <<a href="http://twistedmatrix.com/documents/10.2.0/web/howto/web-in-60/rpy-scripts.html" target="_blank">http://twistedmatrix.com/documents/10.2.0/web/howto/web-in-60/rpy-scripts.html</a>>.)</li>
</ul></div></div></blockquote><div>Huh? The docs you link to claim:</div><div><br></div><blockquote class="gmail_quote" style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0.8ex; border-left-width: 1px; border-left-color: rgb(204, 204, 204); border-left-style: solid; padding-left: 1ex; ">
So, while rpy scripts may be useful for testing out ideas, they're not recommend for much more than that.</blockquote><div><br></div><div>Am I missing something here?</div><div><br></div><div>* * *</div><div><br></div>
<div>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.</div>
<div><br></div><div>I think the reason for this is that I think a lot like Jacob <<a href="http://jacobian.org/writing/great-documentation/">http://jacobian.org/writing/great-documentation/</a>> 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 ;)</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;"><div style="word-wrap:break-word"><div><div><br></div></div></div><br>_______________________________________________<br>
Twisted-Python mailing list<br>
<a href="mailto:Twisted-Python@twistedmatrix.com">Twisted-Python@twistedmatrix.com</a><br>
<a href="http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python" target="_blank">http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python</a><br>
<br></blockquote></div><br>