After some further exploration, I determined that GeoNode was probably too large and complex for our uses; we have existing code and would likely need to scrap most of it, and a lot of the features GeoNode touts just aren't important to us (e.g. social media integration). However, on the off-chance I was being overly pessimistic, I was asked to demo it anyway. While trying to figure out how to get started, I found more documentation, this time in Read the Docs format. Since Read the Docs is quite common in the Python world, I decided the latter documentation was probably more authoritative and certainly better organized.
I began with the quick installation guide. I use Ubuntu on my laptop, so I assumed it would be a simple matter of adding a PPA and sudo apt-get install geonode. Oops, there's no Raring candidate yet, we'll have to use the Quantal version instead. I moved on to the configuration instructions. Now, I only wanted to set up a little demo, so "production" is probably inapplicable in my case, but onwards all the same.
kevin@odin:~$ geonode createsuperuser /usr/sbin/geonode: line 3: django-admin.py: command not found
OK, that didn't work. /usr/sbin/geonode is mercifully a really simple shell script, so I just change django-admin.py to django-admin and try again.
kevin@odin:~$ geonode createsuperuser Unknown command: 'createsuperuser' Type 'django-admin help' for usage.
Well, that's interesting on multiple levels. createsuperuser is a perfectly valid django-admin subcommand, and even appears in its help. But usually, it's executed in the context of an existing Django project via manage.py. The instructions I was given never told me to change directories or anything, they just said to run this and it would work...
I look through the complete installation guide, but that's about installing from source. I certainly hope I'm not going to have to install from source.
I assume the PPA created a Django project for me, and confirm this by pointing a browser at localhost; I'm serving what appears to be a full-blown GeoNode installation via WSGI on port 80, but it hasn't had its static files collected yet, so it looks ugly and broken. If I want to do anything with this project, I'll need to first find it. So I run a locate geonode and come up empty. Well, duh, I need to do sudo updatedb first! With that sorted, I try the locate again and find lots of interesting files and directories, none of which quite look like a Django project. I do manage to find a settings.py and urls.py, but the overall structure of the containing directory is nothing like any Django app I've ever seen. I can't find a manage.py and am basically flying blind.
At this point, I decide to see if the first set of documentation might be more user-friendly. Blundering around, I find a page for creating custom GeoNode projects. These instructions look nothing like the instructions I found earlier and tell me to create a Django project. At this point I'm pretty desperate to get something, anything, working, so I just go ahead and do so. That works (though not without creating a rather worrying error; I also had to steal settings.py from the other installation), but I've still got Apache/WSGI serving port 80. It's around this time that I turn to actually getting our data into the application, never mind which application.
GeoNode may be a Django project, but it doesn't actually use Django's ORM, so far as I can tell. Instead, it uses a system called GeoServer to manage various sources of data. Since they need to support non-SQL data, I suppose this makes sense, but I'm not feeling very charitable right now and the involvement of yet another layer of abstraction irks me. GeoServer has apparently been set up properly by the PPA, so I don't need to do very much. The default username and password aren't working, though, apparently because the PPA was intended for a production deployment, and we all know you can't have a default admin password on a production system. I try to interact with GeoServer's config files, but get nowhere because GeoServer wants you to use its web interface or RESTful API. After fiddling with my GeoNode installation, I eventually manage to create a functional superuser and get into GeoServer. Why does GeoNode auth affect GeoServer, seeing as they're independent? Dunno. From this point, things actually go well enough that I don't really feel compelled to finish the story, but I will say this: I still have that WSGI installation on port 80, and I'm going to keep it until I demo the custom installation because I don't want to break the latter.
So why won't I be recommending this? Well, aside from it not actually serving our needs (we already have some Django code, HTML, and other nice things that we'd have to rebuild or scrap), it has two entirely separate sets of documentation. They don't really 100% agree with each other, and I wasn't able to get a simple installation done without hacking shell scripts, running locate commands, and generally making a lot of guesses. Oh yeah, and I also had to install a Quantal PPA when Raring has been out for over a month and a half.
Yes, I could've just asked on a mailing list about this. But that's not good enough: I was asked to have a report on this ready within the day, and mailing lists can take days to respond at all and weeks to resolve issues. More abstractly, if I need to run to a mailing list just to install the damn thing, we're in trouble. Under the circumstances, how can I recommend this in good faith? If something goes wrong next week and I'm asked to fix it, how can I do so when I don't know the first thing about the installation? If I was asked to roll my custom installation out to production right now, I wouldn't have the first clue where to start, particularly since the PPA already created and configured a production setup entirely by itself. I suppose I'd need to graft the custom installation onto that. How should I? No idea.
Documentation isn't just for clueless end users; we saw this way back in 2006 when ESR played with CUPS. A fancy landing page may be very nice and professional-looking, but it doesn't matter if you don't have usable instructions.
This is not a case of not having enough documentation, either. This is a problem of never testing the documentation. At some point, someone who knows little or nothing about the project should be given the installation instructions and asked to follow them. Instead, this documentation assumes the end user knows where the packages will put the installation.
Of course, other packages might have put the installation somewhere else, so maybe the documentation can't have the installation location. That's no excuse. If the packages were capable of customizing the installation, they should have prompted for it with Debconf (and included a sane default). If they're weren't, they should all harmonize on a particular sane default and document it.
One last thing: I'm sure GeoNode is a great product. This isn't intended to imply otherwise. But right now, its crappy documentation is tarnishing its brand.