Thank you this is helpful. I agree that this part of the site is confusing.
-----Original Message----- From: Gisbert Amm [mailto:[EMAIL PROTECTED] Sent: Thursday, September 27, 2007 4:42 AM To: Maven Users List Subject: Re: Improving Maven Site Docs (was maven is hard) I've recently been confused about the structure of the site myself, even though I'm no Maven beginner. I was looking for information about the Maven packager (for I already knew that the jar-, war- and other packaging plugins use the same packager and I wanted a reference manual for that). There is a section called "Documentation", so I started exploring the subsections. Here in short my thoughts while exploring it: * Index (category) - might not be the right place (What does "category" actually mean?) * Running Maven - I've seen this before and it's only for very beginners. * User Centre - That might be the right place. * Plugin Developer Centre - I don't want to develop a plugin, thank you. * Maven Repository Centre - What's that about? The repository containing Maven or Maven repos containing some artifacts? Never mind. Will not find what I'm looking for in here anyway. * Maven Developer Centre - No, I'm no Maven developer. That's for the gurus only. * External Resources - Don't actually know what's in here. Have to investigate later on. * Wiki - maybe there is something useful in the Wiki. But it's written mainly by other users and I don't trust it too much. Had some experiences in the past where the docs in the Wiki weren't quite right or up-to-date. Also it's difficult to find anything. Rather stay on the official Maven site. So I searched the user centre for a reference about packaging configurations but didn't succeed. After that I came back to the main page and hit the link "Plugins by Category" below the heading "Get Maven Plugins" after I realized that this is documentation too and the heading is a bit misleading (you don't get the plugins from here). At least there are several packaging options described in the plugin documentation of the plugins in the section "packaging types / tools", however, I still don't know if there is a complete reference manual for the packager somewhere. I hope my attempt to describe my experience with the site is of any help when you think about how to restructure it. One other comment about pages like http://maven.apache.org/users/cookbook/index.html: This for me is as annoying as some promising website showing an "under construction" message instead of the expected content. It would be much better if those pages wouldn't be there at all. Please bear with me. If I sound somewhat harsh sometimes it's only because of my insufficient command of the English language and not because I don't want to be polite - at the contrary. -Gisbert Brian E. Fox wrote: > A common theme in the "maven is hard" thread is bad documentation and > I'd like to explore this a little. For the sake of discussion, lets > separate the plugin docs from the maven site. (Why? Because each plugin > site is like it's own little world and some are good and some are bad. > We can have that discussion after) > > > > I took a look at our site again. The first thing I notice is that it is > mostly setup towards grabbing new users with the big "Learning about > Maven" section. This is ok for total newbies, but quickly runs out of > steam. I also took another look at the Ant site that everyone raves > about. The major difference I see is the link prominently titled > "Manual" Once you go into the manual however, it is still a little tough > to drive down to what you need. You have to know what you're looking for > before you can find it. I don't think the Ant manual is all too > different from this page: http://maven.apache.org/guides/index.html > > > > The thing I'd like to know is what is missing from this list that should > be there? > > > > I think there is some potential to be gained from taking all those docs > and arranging them in a more cohesive structure, but I do think that > lots of information is there. Unfortunately we aren't all great > technical writers, nor were the docs written as a book. This is where > the BBWM and Sonatype books come in handy. They are meant as an end to > end resource and where done with some Tech Writing help (I'm assuming > here). > > > > Lets list some positive improvements that can be made to the existing > Maven site in this thread. > > > > Thanks, > > Brian > > > > > > > > > > -- Gisbert Amm Softwareentwickler Infrastruktur Telefon: (0721) 91374 - 4224 Telefax: (0721) 91374 - 2740 E-Mail: [EMAIL PROTECTED] Internet: www.1und1.de 1&1 Internet AG Elgendorfer Strasse 57 56410 Montabaur Amtsgericht Montabaur HRB 6484 Vorstand: Ralph Dommermuth, Matthias Ehrlich, Andreas Gauger (Vorsitzender), Matthias Greve, Henning Ahlert, Norbert Lang, Achim Weiss, Robert Hoffmann, Aufsichtsratsvorsitzender: Michael Scheeren --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
