Technology
We had previously been using Apache Maven and would like to stick with it. Benson Margulies has made the point that it can be difficult to work with (if I recall correctly his preferred tool is Apache Shiro), and one thing that we've learnt is that the generated site (from a mvn site-deploy) must then be checked into SVN as an artifact in its own right. I can see how that might cause some work.
Still, at least some other projects use Maven exclusively, so I think we should go down that route in the first place and see where it takes us.
Dan's note: since I originally wrote this we've deployed a site via people.apache.org; it would seem that it ISN'T necessary to check generated sites into SVN. Perhaps we're doing it wrong, at the mo?
Inspiration
Dave Slaughter had a look around some of the other sites and stated:
I was looking at some of the other Apache projects and I thought the Apache Cocoon site (Dan: built by Maven, pretty to look at) had a pretty good layout that made it easy to get started and worked it's way up to contributing to the project. On the Cocoon site, I find it easy for both the beginner and the advanced developer to find the information they need within a few clicks and the documentation and reference material are easy to find.
Two other sites that I found to be organized well are the Apache Struts (Dan: built by Maven, not pretty) and Apache Wicket (Dan: not Maven) site. I think we can take advantage of some of the styles of these sites and make it easy for all levels of developers to use the site effectively and efficiently.
Aesthetics vs Organization
We probably should distinguish aesthetics from organization. The fact that both Cocoon and Struts are Maven-generated and are easily navigable means that there's nothing wrong with our decision to use Maven as a technology for writing site docs. The thing that is important though is that we get the organization right.
I like the hexagonal architecture picture as a basis, but perhaps hyperlinked to the components. Another non-Apache website that I like a lot is http://metawidget.org; that big picture in the middle works well, I think, along with screencasts. The framework should be easy to consume.