better tutorial for geodjango

[digi_c@…]

Hi, I like geodjango and have some basic knowledge of GIS and django. But I feel, that the tutorial as a way to complex for beginners. It's not completely bad, but I have a few suggestions:

• use primitive data like points (less complex to understand)
• make basic full application (add/edit/show of simple geodata, not only via admin interface)
• show best practise (dataformats instead of WKT, JSON streaming, webmap tiling or clustering)

Maybe anybody has an idea about a rewrite :)

[Serhiy]

IMHO the whole GeoDjango docs should be rewritten from scratch. It's the worst documentation I've seen in years, literally.

It's outdated: https://code.djangoproject.com/ticket/22456
It tries to instruct on usage before installation. ​https://docs.djangoproject.com/en/dev/ref/contrib/gis/
In the installation tutorial in gives you a command to execute and right afterwards adds that it's not needed at all. ​https://github.com/django/django/commit/92b5341b19e9b35083ee671afc2afb2f252c662d#commitcomment-1936761
It doesn't contain any info on integrating GeoDjango into an existing project.
It doesn't even contain clear info about its' benefits over using two FloatFields when all I want is just a simple map of objects: the most widespread use case AFAIU.

[Tim Graham]

Patches are welcome. GeoDjango isn't as widely used as the rest of the Django, so we receive less contributions for it. Using hyperbole and rude comments won't do anything to address the issue. Thank you.

[Serhiy]

Yes, sorry about the rudeness, my bad. I just spent a day trying to dig through this mess. And I'm currently sure that the bad documentation is one of the reasons for less usage.

P.S. I just found that ​https://docs.djangoproject.com/en/dev/ref/contrib/gis/admin/ doesn't contain all options listed in contib/gis/admin/options.py. For example adding display_wkt would be really helpful.

[Sylvain Fankhauser]

I would be happy to work on this.

Here are the things I think could be improved:

• Create an easier tutorial that doesn't require extensive comprehension of world borders, ogrinfo etc that are quite specific. We could go on creating an application that defines models with simple coordinates or shapes and calculates distances between objects. We could make a tutorial that looks like the Django tutorial (1. creating models, 2. the geo admin, 3. using geo data in views/templates/forms).
• Simplify GIS installation of GIS libraries (see #24942)
• Make a better explanation of what GDAL and GEOS are (if the docs are aimed to lambda users, we can assume that the following could be explained better: "GEOS stands for Geometry Engine - Open Source, and is a C++ library, ported from the Java Topology Suite. GEOS implements the OpenGIS Simple Features for SQL spatial predicate functions and spatial operators. GEOS, now an OSGeo project, was initially developed and maintained by Refractions Research of Victoria, Canada.")
• Reorganize/simplify the TOC (GeoDjango installation is placed after the GeoDjango tutorial, although you first need to go through the installation process to proceed with the tutorial). Also this long list of topics is far from being as clear as Django's docs TOC
• This one might be more of a detail but I would use native types (eg. Point) instead of the GEOSGeometry constructor, and try to be consistent along the tutorial

[Claude Paroz]

You are of course welcome to work on this, and your summary looks promising. Feel free to assign the ticket to you as soon as you start working on this.

[Collin Anderson]

I mentioned this on https://code.djangoproject.com/ticket/26442#comment:2 but we should link to the mailing list in our documentation.

[Mark Walker]

I'm reviewing the language used in the docs around GeoDjango, so I'll go through the tutorial as well and see if I can address any of these issues. Though what I've done with GeoDjango has been fairly primitive, plotting routes for races & distances between users & events.