Opened 11 years ago

Last modified 10 months ago

#22274 new New feature

better tutorial for geodjango

Reported by: digi_c@… Owned by:
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

Description

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 (11)

comment:1 by Aymeric Augustin, 11 years ago

Triage Stage: UnreviewedAccepted
Type: UncategorizedNew feature

comment:2 by Serhiy, 10 years ago

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.

Last edited 10 years ago by Serhiy (previous) (diff)

comment:3 by Tim Graham, 10 years ago

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 by Serhiy, 10 years ago

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.

comment:5 by Sylvain Fankhauser, 9 years ago

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 by Sylvain Fankhauser, 9 years ago

Cc: Sylvain Fankhauser added

comment:7 by Claude Paroz, 9 years ago

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 by Sylvain Fankhauser, 9 years ago

Owner: changed from nobody to Sylvain Fankhauser
Status: newassigned

comment:9 by Collin Anderson, 9 years ago

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

comment:10 by Mariusz Felisiak, 3 years ago

Owner: Sylvain Fankhauser removed
Status: assignednew

comment:11 by Mark Walker, 10 months ago

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.

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