Hi Rob -- First, thanks for taking this on. The tutorial indeed needs some good lovin'; glad to see someone stepping up to the plate. I don't have a huge amount of bandwidth these days, but I can commit to writing a bit, and to editing anything you or anyone else writes.
On Fri, Oct 9, 2009 at 9:41 AM, Rob Hudson <r...@cogit8.org> wrote: > * How do people feel about a tutorial that covers a complete site? Like you, I think it's the best way to teach Django. A complete site can show off more parts than just a small example project can. > * How do people feel about that site being Django snippets? Mmmm... that I'm not so sure about. Partly because this steps on already trodden ground -- James' book (Practical Django Projects) goes through djangosnippets as part of the book -- but also because it's a somewhat insular example. That is, pastebins (of which djangosnippets is a particular complex instance of) are the type of tool that really only highly geeky folks use. Django's got a wider audience -- I know Django users who are primarily journalists, designers, biologists, ... -- and ideally the example we use should have relevance to a broad cross-section of Django's audience. Of course, all that said, I don't have a better suggestion other than the tired personal blog example. So once again this is "if you build the bikeshed you get to paint it" territory. > * Comments on the proposed outline? Are there any important steps > missing? Ordered logically? Feel free to add detail to any step. Couple of things: * This new tutorial absolutely should cover pip+virtualenv, most likely right off the bat. * We should de-emphasize the "apps live inside of projects" thing. virtualenv gets the same effect we were shooting for there with much less mess. * Testing ought to be covered from the start -- I'd like to see every little bit cover how to test it. > * Do we cover things not in Django -- like model migrations, search, > RESTful APIs -- using 3rd party Django apps? I think the best idea would be cover how to find, install, and use third-party apps, and then link to some popular ones. But leave the actual how-tos to those authors. > * Would it be possible to do this openly, with easy user comments, > like the Django book? Is that software available? Heh. Sorta. The JS is okay and if you view source you should be able to figure out how to find it; the backend code is a terrible one-off, though. However, I'm not totally sure that comments make a whole lot of sense for documentation. We had comments on the docs for a while, back in the day, and they just confused people. The comments were mostly the type of questions people *should* be asking on django-users or in IRC. Since nobody who could help them was reading the comments, they didn't help at all. The other major open source projects with comments (PHP, PostgreSQL) also seem to show similar trends. PHP's doc comments, in particular, are a morass of bad advice. The ideal, I think, would be a contextual *editing* tool: something like the comment system, but allowing people to suggest changes that editors could easily apply. That way people could fix typos, suggest better wording, etc., but also not confuse the situation with bad comments. > Also, if we're going to pull this off we're going to need people to > help in a variety of ways. So I'm also curious who might be > interested. We'll need: authors to write some sections, reviewers to > give feedback, editors to clean up text and bring uniformity to the > whole thing, developers to make sure the software the tutorial is > describing is coded using best practices and works, a handful of > people to drive the process and foster community involvement, etc. Well, in grand Django tradition, by suggesting this, you've volunteered to be in charge :) But sign me up as an editor (language and code), at least, and I'll try to help out by writing some sections, too. Jacob --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Django developers" group. To post to this group, send email to django-developers@googlegroups.com To unsubscribe from this group, send email to django-developers+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/django-developers?hl=en -~----------~----~----~----~------~----~------~--~---
