Documentation issues hit list

[James Bennett]

With the recent talk of things that need to get done before 1.0, I
think something that'd be great to hit is a list of the thing which
most commonly confuse new users, or which they have the hardest time
figuring out -- getting that information into the official docs would,
hopefully, save a lot of desperate posts to django-users and the IRC
channel.

Here's my list so far:

* The documentation for "get_FOO_display" is in a different location
than the documentation for "choices", and so is easy to miss, leading
to people giving up or producing nastily complex attempts at getting a
human-readable value out of a field with choices.
* Personally, I think all of the
"get_FOO_display"/"get_next_by_FOO"/etc. methods could be handled
better -- nobody ever thinks to search on those names, and so lots of
people never find those methods.
* The "include" method in URLConfs causes an insane amount of
confusion due to people thinking it pulls in a single specific view
instead of another URLConf, and the docs we have don't seem to be
preventing that.
* Lots of people get bewildering "can't parse remainder" exceptions
because they did {{ object.method() }} in a template instead of {{
object.method }}, and the docs which explain how dot-lookups resolve
don't really help much with that.

I'll be filing tickets with suggestions for all of these tonight, and
I've got a few more common pitfalls stashed away on a laptop that's
off for repair, so I'll ticket those when I get it back.

Anybody else got a list like this? I'd love to aggregate as many of
them as possible and get together a "hit list" of this stuff to
document as we go forward.

--
"Bureaucrat Conrad, you are technically correct -- the best kind of correct."

[d...@simon.net.nz]

Good idea, one thing I've been meaning to do is to go through the
tutorials and fix up the various glitchs (there were 4 outstanding
tickets on tutorial 2 last time I looked) and merge in the information
from the comments on djangoproject.com for them.

Why - because the tutorials are the pretty much the first intro.
people have to Django, and they need to work smoothly.

I've done tutorial 1 in ticket #2592 but this needs to be looked over
by someone.

Regarding the get_FOO_display - definitely - I'm embarressed to admit,
but I'm just about to go uh 'refactor' my homegrown choices-to-display
name function because I completely missed this.

Finally, I'm sure a good dig over the django-users list will turn up a
lot of common misunderstandings etc which will reflect doc.
shortcomings. I think some info about debugging would be handy in one
of the tutorials too (e.g. "oops! we did something wrong, here's
Django's debug page, look what we can do here to find out what's
wrong...")

--Simon G.

[David Larlet]

2007/2/8, James Bennett <ubern...@gmail.com>:

>
> Anybody else got a list like this? I'd love to aggregate as many of
> them as possible and get together a "hit list" of this stuff to
> document as we go forward.

A complete tutorial (not just a todo-list or a blog) with customized
middleware, templatetags, generic views is missing. Reading a doc is
boring, following a tutorial, even if it's a big one, which reflect a
real application with real problems is always appreciated.

I've already linked the symfony askeet project [1] which is a good example.

Just my 2cts,
David

[1] : http://www.symfony-project.com/askeet