Opened 6 years ago

Last modified 4 years ago

#22274 assigned New feature

better tutorial for geodjango

Reported by: digi_c@… Owned by: Sylvain Fankhauser
Component: GIS Version: 1.6
Severity: Normal Keywords:
Cc: Sylvain Fankhauser 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 (9)

comment:1 Changed 6 years ago by Aymeric Augustin

Triage Stage: UnreviewedAccepted
Type: UncategorizedNew feature

comment:2 Changed 5 years ago by Serhiy Zahoriya

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 5 years ago by Serhiy Zahoriya (previous) (diff)

comment:3 Changed 5 years ago by 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.

comment:4 Changed 5 years ago by Serhiy Zahoriya

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 5 years ago by 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

comment:6 Changed 5 years ago by Sylvain Fankhauser

Cc: Sylvain Fankhauser added

comment:7 Changed 5 years ago by 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.

comment:8 Changed 5 years ago by Sylvain Fankhauser

Owner: changed from nobody to Sylvain Fankhauser
Status: newassigned

comment:9 Changed 4 years ago by Collin Anderson

I mentioned this on but we should link to the mailing list in our documentation.

Note: See TracTickets for help on using tickets.
Back to Top