The problem, as I see it, is that the documentation is fragmented. Unlike Hibernate and Spring, which provide a single reference manual which is kept up to date with every release, Maven documentation is spread all over the place (wiki, generated sites, better builds with Maven, etc.). The problem gets worse with the isolated documentation for plugins. Plugins may make sense from a technical point of view, but an end-user can care less about plugin seperation from the core. They want to see consistent documentation for all features, whether those are provided by the core or by plugins. By forcing ALL documentation to be centralized (e.g. in a reference manual), you naturally get better consistency and logical flow between the different pieces (Instead of a bunch of isolated how-to's and plugin pages). What a mess Spring's documentation would be if they'd start generating seperate web sites for each framework they integrate with!
Users have been complaining for years about Maven documentation and I agree with those who say that this is a break on wider Maven adoption. As an experienced user, I have no trouble finding what I am looking for but I can tell you from my experience dealing with many new users, that the newbies have big trouble finding their way through the documentation jungle. More than once have I seen projects giving up just because they didn't find an easy way to get started. This is highly regrettable as they are missing out on a great tool! So my recommendation would be: 1) Centralize documentation (prefereably on a wiki so that users can comment on questions). Why not take the Merger book as a starting point? 2) Update documentation with every release. An undocumented feature is an unexisting feature. Thomas On 11/2/06, Adam Hardy <[EMAIL PROTECTED]> wrote:
Wendy Smoak on 02/11/06 22:34, wrote: > On 11/2/06, Sebastien Brunot <[EMAIL PROTECTED]> wrote: > >> What I meant by "it" was the comment mechanism. > > Right... it doesn't exist yet, we need to design it. The comment mechanism can be a wiki where the public can only add at the bottom of the page, and the contributors are the ones who sort out the wheat from the chaff occasionally to enhance each page from its comments. > Earlier, I asked, "Any ideas on how to present that as an option? It's done at mysql[1], php and someone said Hibernate and I think Drupal. But my quick investigation there didn't show anything. Check out mysql though. Perhaps their documentation publishing framework is OS. > What would the menu link be called? How should the pages on the wiki > be organized?" I think the whole maven documentation website should be wiki-commentated (is that the correct verb here??) So each plugin remains as it is except the wiki-commentary can be appended to the bottom of every page. I think that any plugin that makes it onto repo.maven.org should get its docs site on the website too, at least for the releases. regards Adam [1] http://dev.mysql.com/doc/refman/5.0/en/linux-rpm.html --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
