Feedback on improving GeoDjango docs

[Sylvain Fankhauser]

Hello,

I'm currently working on ticket #22274, which is an effort to improve the GeoDjango documentation to make it more accessible to newcomers. This represents quite some work and I'm still in the early stages but I'd love to have some feedback on the general structure I'm planning to create. You can find the current status of the potential new docs here: http://sephii.github.io/django-22274/ref/contrib/gis/index.html (current version of the docs can be found here https://docs.djangoproject.com/en/1.9/ref/contrib/gis/).

The tutorial part is not yet representative of what I'm planning to do so no need to check that yet. That said, I found it quite difficult to come up with a tutorial topic that would allow me to get through most of the features from GeoDjango. So if you have an idea for a usecase I could use for the tutorial, this would be more than welcome.

Some other things I have on my todo list are:

* Clarify installation instructions, split the platform-specific instructions into separate documents

* Check if we can try to merge together some parts in the "Models" section (ie. GeoDjango Database API, Geographic Database Functions and GeoQuerySet API Reference), which all serve the same purpose

If you see anything else, feel free to comment.

Cheers,

Sylvain

[Mattias Linnap]

Great to hear, GeoDjango documentation has always seemed half-finished to me, and only useful to people who are already familiar with GIS terminology.

Based on my impressions from various forum posts over the years, beginners who are looking at GeoDjango:

* Have never heard about OGC geometries, PostGIS, WKT, WKB, SRIDs, ESRI Shapefiles, GEOS, GDAL and Proj libraries, etc.

* Have some understanding of Google Maps and GPS longitude & latitude coordinates.

Their main questions seem to be:

* How to have models of "places" which have a location field, and how to find N nearest places, all places in the currently visible map region, or distances between places.

* Is it worth learning GeoDjango for this, or should they just add two FloatFields to the model.

For example:
https://www.reddit.com/r/django/comments/4csqm0/im_wondering_if_geodjango_is_overkill_in_my_case/
https://www.reddit.com/r/learnpython/comments/4240va/making_a_webapp_in_django_how_to_do_locationbased/

For the tutorial, the content might cover:

0: Installation of required dependencies, with recommended versions (otherwise they get scared of the version compatibility matrices at https://trac.osgeo.org/postgis/wiki/UsersWikiPostgreSQLPostGIS). Explaining the purpose of each dependency can be a separate optional page.

1: A "places" type model, with N nearest + distance or region lookups. It should default to WGS84 coordinates, leaving the discussion of other coordinate systems for later.

1.5: Best practices for displaying the places on a map in the browser with some Javascript library (OpenLayers, Leaflet or Google Maps).

2. In a more advanced tutorial, perhaps adding some more complex geometries like polygons for regions or linestrings for GPS tracks, and operators like contains or intersections.

For the theme around the tutorials, I'm sure restaurants, apartments for rent, ice cream kiosks, or elephants in natural parks work equally well. :)

Mattias

[Tim Graham]

I'm not sure about expanding and/or splitting the platform-specific instructions. These are not so well maintained and might be better suited for some wiki pages or something, e.g. https://code.djangoproject.com/ticket/25633.