Opened 21 months ago

Last modified 6 months ago

#22274 assigned New feature

better tutorial for geodjango

Reported by: digi_c@… Owned by: sephii
Component: GIS Version: 1.6
Severity: Normal Keywords:
Cc: sephii Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no


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 :)

Change History (8)

comment:1 Changed 21 months ago by aaugustin

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted
  • Type changed from Uncategorized to New feature

comment:2 Changed 7 months ago by int-ua

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

It's outdated:
It tries to instruct on usage before installation.
In the installation tutorial in gives you a command to execute and right afterwards adds that it's not needed at all.
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.

Last edited 7 months ago by int-ua (previous) (diff)

comment:3 Changed 7 months ago by timgraham

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.

comment:4 Changed 7 months ago by int-ua

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 doesn't contain all options listed in contib/gis/admin/ For example adding display_wkt would be really helpful.

comment:5 Changed 6 months ago by sephii

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

comment:6 Changed 6 months ago by sephii

  • Cc sephii added

comment:7 Changed 6 months ago by claudep

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.

comment:8 Changed 6 months ago by sephii

  • Owner changed from nobody to sephii
  • Status changed from new to assigned
Note: See TracTickets for help on using tickets.
Back to Top