Opened 11 years ago
Last modified 10 months ago
#22274 new New feature
better tutorial for geodjango
Reported by: | 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 , 11 years ago
Triage Stage: | Unreviewed → Accepted |
---|---|
Type: | Uncategorized → New feature |
comment:3 by , 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 , 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 , 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 , 9 years ago
Cc: | added |
---|
comment:7 by , 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 , 9 years ago
Owner: | changed from | to
---|---|
Status: | new → assigned |
comment:9 by , 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 , 3 years ago
Owner: | removed |
---|---|
Status: | assigned → new |
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.