Good day to you all, fellow Maven Users, I agree that right now, maven documentation is scattered. We have the apache maven site ([1]), the docus you can build with the source code (checkout the source and do mvn site [2]...and btw, the maven site can be checked out as well [3]), the mailing list [4], BBWM ([5]), the wiki, and other 3rd party sources. Furthermore, the maven users community must be able to participate in maven's documentation. Maven is an open source project, and just like any other open source project, it's only as good as the community backing it up.
So how do we get more involvment from the maven users community? MAVEN SITE A suggestion make the apache maven site wiki-like, so that users can be involved in the documentation as well. Maybe we can lobby this with the maven developers. Currently though, if a non-committer wants to contribute something to the documentation, the process would be to create a JIRA issue, create a patch, and submit that patch. However, you won't see the changes until the patch gets approved. So it would be nice if we can have a staging site if we can't make teh maven site wiki-like. These staging site can be linked to actual page itself for easy access. Furthermore, links to the mailing list and wiki should be move visible. This will make the maven site the center of all these documentations. DOCS FROM SOURCE CODES For those docs that are build from the checked-out code, they're already incorporated in the maven site. For those that are not included in the maven site, that means that those built docs are for the current unreleased versions. The docs found in the maven site are for the released. So if you're using a snapshot and you want to find the docs for it, try doing mvn site. if something comes, good for you. if none, oh well. IMO, docs should only be updated every before release anyway (which is currently happening wit the apache maven plugins). MAILING LIST As for the mailing list, as of now, if we want something from the mailing list, we have to search for existing information (which may or may not be updated or true), or ask it. I'm not sure, but i don't think there's a "pin thread" option here. Also, there are no subcategories (for the maven-users) for easy searching. What we could probably do is to create subcategories (subforums). As to what these subcategories are, im not sure...any suggestions? Also, maybe we can provide a wiki section for each category, so that we can store there important information...sort of a maven users notes. Furthermore, going back to the maven site is now possible thanks to the new skin of the maven forums in nabble. BBWM Maybe this can be one of the subcategories (subforum)..and of course, with its own wiki section. But since we can't submit patches for BBWM, the maven users must maintain this wiki section to be more organized. WIKI IMO, the only problem right now with it, is that it's a bit unorganized. Any thoughts on how to reorganize it? The only thing I can think of right now is to provde links on every page (or at least wiki section) to the maven site. WDYT? Cheers, Franz [1] http://maven.apache.org [2] http://svn.apache.org/repos/asf/maven/site/trunk/ [3] http://www.nabble.com/Maven-f177.html [4] http://www.mergere.com/m2book_download.jsp [5] http://docs.codehaus.org/display/MAVEN/ Gisbert Amm-3 wrote: > > 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-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] >>> > >>> > >>> >>> >> >> > > -- > 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] > > > -- View this message in context: http://www.nabble.com/Maven-rant-tf2544811s177.html#a7184794 Sent from the Maven - Users mailing list archive at Nabble.com. --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
