OK. I like this, too, but there's already the mechanism for doing this in the form of documentation for the individual components.
Specifically, the "how to use" sections of most of the plugins, which are a huge portion of the "how to maven" world, are weak. However, since it requires the knowledge of HOW to use the plugin in order to write docs on how to use the plugin, generally only the developers could possibly write such docs. And so we're back to the same problem from a slightly different angle. I do very much like the idea that the site docs are all you should need, though. +1 ( sort of :) ) On 11/2/06, Gregory Kick <[EMAIL PROTECTED]> wrote:
Ok, this is think outside the box time... I like Thomas' comments on centralizing documentation. I really, really like Thomas' comments on centralizing documentation. However, I think the logistics may be off. I'm thinking of the documentation problem as similar to the build problem. Before there was maven, users had to go from site to site downloading jars and collecting them into a useful, coherent code base every time they wanted to build because a bunch of different groups contributed a bunch of small, but useful artifacts. That got fixed. Unfortunately, we're now finding that users are going from site to site browsing documentation and collecting it into a useful, coherent knowledge base every time they want to understand something because a bunch of different groups contributed a bunch of small, but useful bits of documentation. So, here's what I propose: Lets create a repository for documentation. The docs will exist within the projects, as they do now, and we'll use an APT/Wiki hybrid that allows for linking between projects (e.g. [[groupId:artifactID]]) and documents (e.g. guides, javadocs, etc.) within those projects. That way, there's quality control because the docs have to be committed, we avoid the unrealistic make-a-giant-book-that-somebody's-going-to-be-in-charge-of-because-I-don't-want-to plan, and we get the centralized feel with out having to duplicate the little bits of usefulness that already exist. Obviously, there will be a lot of gaps, broken links, etc. in the early stages, but I don't think that it would be any worse than with a typical wiki. There may be a slower turnaround in updates, but that might be balanced out by the fact that current documentation could be reused. Later, if we want something more interactive there could be a tool for generating and submitting documentation patches via this online repository. So that's my little bit of brainstorming. There are obvious issues like hosting, but for now I dare to dream... :-) Thoughts? On 11/2/06, Thomas Van de Velde <[EMAIL PROTECTED]> wrote: > 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] > > > > > > -- Gregory Kick http://kickstyle.net/ --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
-- I'm just an unfrozen caveman software developer. I don't understand your strange, "modern" ways.
