On Tue, Feb 1, 2011 at 4:15 PM, Glyph Lefkowitz <span dir="ltr"><<a href="mailto:glyph@twistedmatrix.com">glyph@twistedmatrix.com</a>></span> wrote:<br><div class="gmail_quote"><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
<div style="word-wrap: break-word;"><div><br><div>OK. For what it's worth I share your desire for a new / better term but I can't think of one.</div><br></div></div></blockquote></div><br>Recipes? Snippets? Tidbits? Morsels? Quickies? "How do I..."s? Quick Examples? Simple Examples? Examples? Blurbs?<br>
<br>A lot of the various example scripts actually fulfill this function, though if you don't know about them, you're out of luck. And they have no explanatory text to go along with them.<br><br>Some of the questions in the FAQ fulfill a similar purpose, I think, and would benefit from a simple example to link to.<br>
<br>I'd like to see a bajillion of these, but only if we have a way to test the sample code. Otherwise it's a maintenance nightmare. (Note that when stuff changes and the example code breaks, it's also a flag to update whatever docs point to it, so the idea of testing sample code isn't just to help the code, but also the narrative docs that go along with it.)<br>
<br>----<br><br>I agree with Glyph that "templates" to guide docs authors would be an excellent tool to have.<br><br>----<br><br>As far as Jacob KM's documentation series, I also think it's pretty good, so let's compare Twisted's docs to what he suggests to write:<br>
<ul class="simple"><li>step-by-step tutorials,</li></ul>Twisted has precisely one of these (the finger tutorial). A lot of people hate it. It should be fixed or replaced, and we should also have more of these. You could probably also count web-in-60 as one of these, too I guess, so maybe we have 2.<br>
<ul class="simple"><li>overviews and topical guides to the various conceptual areas of your
project, and</li></ul>Pretty much anything in the various "howto" directories, though in the docs themselves they tend to be called "Developer Guides" (which I think is a better name). We have a lot of these, they just need to be better organized/edited, and a bit more coherent. Some are fantastic. Some are stubs. Some are out of date. Some are flat wrong.<br>
<ul class="simple"><li>low-level, deep-dive reference material.</li></ul>The API docs. Which are great in some places, dismal in others. There needs to be a systematic review of this to figure out what's missing. A "template" for docstrings wouldn't be a bad tool to have either.<br>
<br>Kevin Horn<br>