+1
This would make it even possible to create a user/project dedicated manuals. The project pom-file already has all plugins being used by the project. The generated manual will then just include the docs for these plugins and use the actual plugin version. Regards, Minto -----Oorspronkelijk bericht----- Van: Gisbert Amm [mailto:[EMAIL PROTECTED] Verzonden: vrijdag 3 november 2006 9:43 Aan: Maven Users List Onderwerp: Re: Maven rant Why not use the central repo for documentation aswell? E.g. in http://www.ibiblio.org/maven2/plugins/org/apache/maven/plugins/maven-ant-plugin/2.0-alpha-2/ could exist a bundle named user-manual.zip, containing the sources for the user-manual. There could be a reference-manual.zip, a developers-manual.zip and so on. The Wiki pages could be generated out of these sources. One step of the release process of a plugin (or the Maven core) would be to integrate possible user comments from the wiki into the documentation sources and regenerate the respective wiki pages. A Maven plugin could be written to download all document sources of a certain category, bring them into a reasonable order (defined by models within the plugin), add introductionary material from common bundles, table of contents, indexes etc. and produce a users manual, reference manual and so on in a format the user can choose (HTML, PDF ...) Even the Maven website could be produced by such a plugin; it would just be defined by another documentation model. Just applying the same principles used for software production to documentation ... I hope I was able to make myself understood (sorry for my English) and am not dreaming too far into the blue ... -Gisbert Gregory Kick 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-d > on'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] >> > >> > >> >> > > -- Gisbert Amm Softwareentwickler Infrastruktur WEB.DE GmbH Brauerstraße 48 · D-76135 Karlsruhe Tel. +49-721-91374-4224 · Fax +49-721-91374-2740 [EMAIL PROTECTED] · http://www.web.de/ --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] DISCLAIMER De informatie in deze e-mail is vertrouwelijk en uitsluitend bestemd voor de geadresseerde. Indien u niet de geadresseerde bent, wordt u er hierbij op gewezen, dat u geen recht heeft kennis te nemen van de rest van deze e-mail, deze te gebruiken, te kopiëren of te verstrekken aan andere personen dan de geadresseerde. Indien u deze e-mail abusievelijk hebt ontvangen, brengt u dan alstublieft de afzender op de hoogte, waarbij u bij deze gevraagd wordt het originele bericht te vernietigen. Politie Amsterdam-Amstelland is niet verantwoordelijk voor de inhoud van deze e-mail en wijst iedere aansprakelijkheid af voor en/of in verband met alle gevolgen en/of schade van een onjuiste of onvolledige verzending ervan. Tenzij uitdrukkelijk het tegendeel blijkt, kunnen aan dit bericht geen rechten worden ontleend. Het gebruik van Internet e-mail brengt zekere risicos met zich. Daarom wordt iedere aansprakelijkheid voor het gebruik van dit medium door de Politie Amsterdam-Amstelland van de hand gewezen. --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
