Version 4 (modified by stumbles, 12 years ago) ( diff )

--

      1. Tutorial app selection
      2. Topic area: best practices
      3. Brainstorming whiteboards

Tutorial app selection

There are many goals in a tutorial - a sales pitch for the framework, a guide to salient points, an explanation of benefits/strengths, a starting point for best practices, and so on. And it serves at least 3 archetypical users - new to programming, new to webdev, and new to python/Django.

There was some discussion of replacing the Polls app with a Blog app, because 1) more people would clearly understand what a blog is and 2) the resulting code might be useful and used at the end of the tutorial. These motivations are good, but the existing app covers the following parts of django. If we intend to replace the app, we need to make sure it's useful towards the overall goals of the tutorial noted above. So which features do you think those are? ​Submit suggestions and/or upvote existing ones.

Features currently covered:

  • url dispatch
  • views/request/response objects
  • templates, rendering
  • startproject/startapp/project layout
  • model/fk/syncdb
  • admin
  • timezones
  • forms
  • csrf
  • generic views

Topic area: best practices

There is a ​what's next page linked from the 4th page of the tutorial, but it mostly talks about directions to head in the django docs. It would be nice to list some pointers for ​best practices.

Brainstorming whiteboards

Installing Django is under-documented by the tutorial; eg. virtualenv

We set users up for failure because we don't explain that migrations are important.

We make the question of deployment confusing and opaque.

We can provide "hints" that the user can optionally show/hide if they want more background.

3 groups to address:

  1. Total beginners
  2. People coming from other frameworks
  3. ?

Parametrize the tutorial?

  • JS show/hide parts
  • check off boxes at beginning about your level of experience

Google App Engine? Beginners very often come to Django thinking GAE will be the easiest way to deploy, but that's incorrect. Why we need to also point to Heroku (and other?) options.

Projects suggestions:

  • Redesign docs homepage:
  • break down into topics
  • make it easier to find things
  • Django explained to rails developers
  • No more Polls
  • class based views!

Lots of people still use The Django Book

Test runner confusion with creating/deleting databases

Not enough info on testing views in particular as opposed to general unit-testing. Maybe part of testing reference docs?

Other tutorials need to be linked, eg. how to use pip/virtualenv

Suggested types of tools, eg. you probably should use a migration tool

List of links to step 5

Different versions by different vendors?

But also why. Why even deploy your project. What does that mean?

Python sucks on Windows.

People sometimes don't know how to use the command line.

"Where's my button?"

Need to point to good outside tutorials for this.

Encourage them to use virtualbox? But that turns newbies off.

What about when people get through the tutorial and come out not knowing about platform-specific basics, like Windows env vars?

Tutorial page 1

Settings file

At least have user change timezone and provide a link to the timezones used.

What? There's an FAQ? Maybe update/integrate it somehow.

Need best practises.

  • What is a project? an app?
  • What about that apps/ folder practise?
  • What about cross-app situations?
  • Maybe make this part 5?

Coming from Rails:

  • View and controller confusion
  • Non-textbook MVC
  • Template == Views??
  • Even for beginners who hear about "MVC", a high-level/big picture would be useful
  • Hints on the side for learning more Python, or inline boxes

(Original whiteboard images: ​http://imgur.com/a/GeHDI)

Note: See TracWiki for help on using the wiki.
Back to Top