"First App" is Way Too Complex - Some Suggestions
|Reported by:||Owned by:||nobody|
|Has patch:||no||Needs documentation:||no|
|Needs tests:||no||Patch needs improvement:||no|
For a novice, or PHP convert, or even a Rails convert (I'm versed in PHP and Rails), the "Your First App" is way,way too complex. The important thing here is too remember the 80/20 rule - that users are going to use 20% of the features 80% of the time - so in the "First App" you just want to highlight the 20%. All the rest of the documentation should go into a Users Guide. I'm happy to modify/submit changes to "Your First App" documentation as we build our first Django App. What is really the best way to do this ? Should we download a section, send in our modifications ? Or just give a section by section change here (which means someone else does the actual page changes (feel free to email me). Also a testing section is really needed - testing should be both demonstrated as part of the initial stages as well as encouraged. I've written up a section on testing (but I used James Bennett's to do list example). I'll put that on a separate ticket.
One big decision is whether or not a user wants to use the Admin or their own CRUD via NewForms. I think it's important to include a paragraph (see below) to let users decide which they want to use to add/edit/delete their data and then direct them to the appropriate section. We would rather use NewForms but not sure if we are majority, minority or even split.
Add, Edit, Delete Your Data
Once you have a model described, the next function is to provide for adding, editing, or deleting your data. Django offers 2 primary ways to do this:
Admin and NewForms. [perhaps you just want to use "Forms" instead of "New Forms" since people reading this are new users and not used to the old forms].
First, you can use the Admin library. This library automatically provides a built-in system for managing data, arranging data fields in a tabular form.
[merge in all the admin stuff]
You may wish to custom design your data forms like the way it's done with most other web development packages such as PHP and Rails. Django also makes this easy via it's NewForms library. [merge in New Forms stuff]