A conversation on IRC about helping people develop with GNOME led to a focus on documentation as being a huge problem in getting the word out. GNOME's existing documentation resource is developer.gnome.org.
I figured I'd do a mini-review of this site. This isn't intended as an affront to those who've put the site together: I'm well aware of the resource limitations that are involved.
The immediate difficulty you see when landing on the front page is audience confusion: "for those who develop, or are interested in developing GNOME, and applications for GNOME." These two constituencies are radically different. Those developing GNOME itself want more cutting edge information, and don't mind stuff that's rougher. Those developing against GNOME want to have accessible information about stable APIs. I think the hacker audience's needs can be met as a subset of this site, but that the site itself should predominantly be for those programming against GNOME. We need to decide and make plain who the audience is.
There's also no context on the front page: if I didn't know the current stable version of GNOME is 2.4, I'd really have little hope of finding out. And what guarantees are there for apps programmed to 2.2, etc, etc. A lot of basic contextual and introductory information is omitted.
The developer home page is static, and the prioritisation of items leaves a lot to be desired: the first item, "News", wasn't updated between July and November, giving a bad impression. Furthermore, much of the news is GNOME-hacker oriented and maybe not of general interest to people wanting to develop against GNOME for their job. "Release Planning" is again useful, but only for a minority.
The "Feature Article" is a great idea, but pretty much undeveloped. The articles aren't dated, illustrated, or well formatted. The current feature should also be promoted to the front page to draw people in.
The "Architecture" section is handy, but should probably be re-set in a context of an introduction to programming with GNOME.
The "Documentation" section is the holy grail and ought to be much more prominent. It does, however, need a complete re-architecting. It's put together as basically a directory structure, and often disappoints. For instance "Programming Guides" promises "In-depth, detailed descriptions of the GNOME architecture" but leads to a selection of odds and ends. Some content is also so outdated it should be retired. Again, the confusion over the audience creates problems. This section is oriented largely from the point of view of those developing GNOME itself.
The API docs are obviously useful--vital, really--but quite incomplete. Also, there are no handy links to the tutorial sections from the relevant parts of the API documentation. Additionally, I see nothing about using languages other than C.
Overall, the developer site is little more than a basic tree structure for a jumbled collection of documents. There is no cross linking and, horrors, no search! There's no editorial voice, context, or way of drawing people into the content, and even content that does change and update isn't surfaced in any way on the developer home page.
My recommendation would be to develop a site aimed at the end-user of the GNOME development platform, with many of the characteristics of modern developer resources such as MSDN. The information aimed at those who wish to contribute to GNOME must still be kept, but ought to take a back seat. Some decent editorial resource needs to be invested in creating an information architecture for the site and in creating content that draws readers in.
In short, GNOME needs what it probably can't afford: full-time editorial resource on a developer site.
