Changes between Version 2 and Version 3 of TutorialImprovementSprint

08/19/12 21:21:50 (3 years ago)

Transcribe whiteboard images.


  • TutorialImprovementSprint

    v2 v3  
    2626=== Brainstorming whiteboards ===
    28 Here are some pics of whiteboards we used for brainstorming areas for improvement:
     28Installing Django is under-documented by the tutorial; eg. virtualenv
    31 (Reader, please transcribe these into text here if you have time; the images may die some day.)
     30We set users up for failure because we don't explain that migrations are important.
     32We make the question of deployment confusing and opaque.
     34We can provide "hints" that the user can optionally show/hide if they want more background.
     363 groups to address:
     381. Total beginners
     392. People coming from other frameworks
     42Parametrize the tutorial?
     44* JS show/hide parts
     45* check off boxes at beginning about your level of experience
     47Google 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.
     49Projects suggestions:
     51* Redesign docs homepage:
     53  * break down into topics
     54  * make it easier to find things
     56* Django explained to rails developers
     58* No more Polls
     60* class based views!
     62Lots of people still use The Django Book
     64Test runner confusion with creating/deleting databases
     66Not enough info on testing views in particular as opposed to general unit-testing. Maybe part of testing reference docs?
     68Other tutorials need to be linked, eg. how to use pip/virtualenv
     70Suggested types of tools, eg. you probably should use a migration tool
     72List of links to step 5
     74Different versions by different vendors?
     76But also why. Why even deploy your project. What does that mean?
     78Python sucks on Windows.
     80People sometimes don't know how to use the command line.
     82"Where's my button?"
     84Need to point to good outside tutorials for this.
     86Encourage them to use virtualbox? But that turns newbies off.
     88What about when people get through the tutorial and come out not knowing about platform-specific basics, like Windows env vars?
     90Tutorial page 1
     92Settings file
     94At least have user change timezone and provide a link to the timezones used.
     96What? There's an FAQ? Maybe update/integrate it somehow.
     98Need best practises.
     100* What is a project? an app?
     101* What about that apps/ folder practise?
     102* What about cross-app situations?
     103* Maybe make this part 5?
     105Coming from Rails:
     107* View and controller confusion
     108* Non-textbook MVC
     109* Template == Views??
     110* Even for beginners who hear about "MVC", a high-level/big picture would be useful
     111* Hints on the side for learning more Python, or inline boxes
     113(Original whiteboard images:
Back to Top