On Thu, 2003-12-18 at 16:29, Chad McHenry wrote:Maybe that could work. I was thinking the top level of the Documentation should start out with "Manual" (or "User Guide" or some sort of item that indicates it's the canonical manual for how to use the projects software) followed by "JavaDoc". The rub is that it really depends on what the project is for. For a project like Maven, you don't necessarily need JavaDoc listed with that much importance. There you might want a reference to the xml tags available. For a library style project (most of mine) you'll want the JavaDoc for it to be very prominent under the "Project Documentation"
One thing I'd like to see changed is having "JavaDocs" and "Source Xref" promoted from being "Project Reports". I would consider these more than just reports: they are significant documentation! There's even a "JavaDoc Report" to emphasize the point!
Would you like to see JavaDocs in the quick links section? Chris
Stevenson also suggested this. As it is a pretty hot item it could be
moved into the quick links section. This is the kind of feed I'm looking
for.
A few other thoughts come up.
The first link under "Quick Links" should be "About Foo" (currently under "Project Documentation"). It's definitely the de-facto norm to list "Home" as the first item in a web site's nav menu, which is really what "About Foo" is for a Maven generated site: it is the 'index' page which all others are subordinate to. It's very strange having the index page referenced half way down the menu!
Are both "Overview/Reference" and "Documentation" necessary? Semantically, the names are very close, and I've no solid, intuitive reason to look in one, and not the other for a particular piece of information. Case in point: JavaDoc is [usually] more of a "Reference" document, than a "Documentation" document. I expect it to be under "Documentation" for some reason, though I wouldn't be surprised to find it under "Reference". IMO, this is the kind of ambiguity Maven should help (non web designing developers) to eliminate.
...Chad
Howdy,
Prompted by Chris Stevenson Bob and I have started playing around with the Maven generated site in order to make it easier to navigate and more useful. Currenlty the book I'm working with is Homepage Usability by Jakob Nielsen:
http://www.amazon.com/exec/obidos/tg/detail/-/073571102X/qid=1071679585/sr=1-1/ref=sr_1_1/104-5601731-6202321?v=glance&s=books
There are 113 recommendations so I'm slowly working through them to see what makes sense and what can be applied to the Maven generated site.
As a simple start we've tried to make the site look better and not be so much a punch in the face when you first see it. Of course, this is purely subjective but we'll refine the design as we go.
On the main Maven site now you'll notice that there is a "Quick Links" section. Currently I have this hardcoded into Maven's navigation.xml but it is something that I would like to generate for the standard site. I put a few entries there but suggestions for other hot items, like, Javadoc, FAQs are welcome. We'll take the most popular suggestions and add them to the "Quick Links" section or whatever it ends up being named.
I've also started going through some of the reports and the first one I fixed was the dependencies report which Norbert pointed out as being too verbose. I agree so I changed the report back to its original terse format.
I'll be going through the rest of the reports, comparing with some books I picked up but user feed back here is most important. I'm going to do a little more tweaking then I'm going to release the plugin. Hopefully people can try deploying their own sites and asking their users what they feel is important. I think in a couple weeks with some good feedback we can make some vast improvements to the standard generated site. I also have only looked at the site using Mozilla/Linux so there very well might be some problems with other platforms. Please just pop a note in JIRA if you see something that looks horrible.
Take a peek at the work in progress:
http://maven.apache.org/
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
