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]
