Re: Maven rant
Wendy Smoak wrote: On 11/16/06, Adam Hardy Secondly the comments functionality or the link to the wiki is a pretty urgent requirement for me, and I think I'm a typical user. Where are you looking to add comments? Honestly I don't think we're going to get a 'comment mechanism' on the existing site. It's static html generated from apt and other sources. Of course it would need a bigger investment of time and effort, but I'm sure it's the best mechanism. It puts the comments right next to the main documentation and requires no clicking to go anywhere else. But I can only give you my opinion :) I have used all of the other documentation methods and the comment mechanism stands head and shoulders above the rest. But I can imagine that it may not be possible to integrate APT-based generated docs into drupal or other frameworks that do that. I should say just adding a link on the 'Related Links' section with the camelCase name would do it - something like [Maven Wiki: WarPlugin] - but now I see the mavenuser space doesn't use camelCase, so perhaps it's not appropriate. (I thought camelCase was universal wiki style?) all the best Adam - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Maven rant
Wendy Smoak wrote: I had problems today finding some documentation on the war plugin. Pretty standard stuff but I couldn't even find the plugins documentation start page in the left-hand menu, rather I found it on the home page (where I happened NOT to be to start with) in the text. I think this is a symptom of the extensive nature of the maven docs, but still it's pretty fundamental. The left hand menu says "Get Maven Plugins -> By Category". I've seen at least one other comment about it, and this week I had a new person at work also not find it when told, "Click on the 'get plugins' link on the menu." I think we're scanning the leftmost text, and not ever finding the word "plugin". Unless someone has another suggestion, I'm going to try "Plugins by Category". I am not sure why you use "Get Maven Plugins". That smells like 'Download'. The link points to documentation, so surely it should be under the documentation section (instead of being on its own). If it was, it would be simple to call it plain ol' "Plugins". However the 'About' menu is also more or less all documentation too. Maybe you should ditch 'Documentation' and have a more specific 'Reference' section, and move other less reference-y type links to other sections. Otherwise it is very good! - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Maven rant
Wendy Smoak wrote: Any thoughts on what a menu link on each plugin site might be called? For example, I'm planning to link Maven Javadoc Plugin http://maven.apache.org/plugins/maven-javadoc-plugin to its wiki page http://docs.codehaus.org/display/MAVENUSER/Javadoc+Plugin Just "Wiki" seems insufficient (especially since there's already a "Wiki" link on the main Maven site that points to the top of the MAVENUSER space.) Something that refers to "MAVENUSER" in the link? "Docs, contributed by Maven users", but somehow shorter. "User contributed docs"? "User added docs"? -Gisbert Amm - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Maven rant
On 11/16/06, Adam Hardy <[EMAIL PROTECTED]://mail.google.com/mail/> wrote: Just wanted to dredge up this old thread concerning documentation to find out what status it has now after the last conversation. I think this was already in the works when this thread started, but the plugins and guides are now organized by category instead of just a long list, and the index page and main site menu have been reworked. For example: http://maven.apache.org/guides/index.html http://maven.apache.org/plugins/index.html Then we decided that the benefit of publishing up-to-date plugin sites outweighs the possible confusion caused by as-yet-unreleased features showing up, and all but one or two of the plugin sites have been published. I had problems today finding some documentation on the war plugin. Pretty standard stuff but I couldn't even find the plugins documentation start page in the left-hand menu, rather I found it on the home page (where I happened NOT to be to start with) in the text. I think this is a symptom of the extensive nature of the maven docs, but still it's pretty fundamental. The left hand menu says "Get Maven Plugins -> By Category". I've seen at least one other comment about it, and this week I had a new person at work also not find it when told, "Click on the 'get plugins' link on the menu." I think we're scanning the leftmost text, and not ever finding the word "plugin". Unless someone has another suggestion, I'm going to try "Plugins by Category". Secondly the comments functionality or the link to the wiki is a pretty urgent requirement for me, and I think I'm a typical user. Where are you looking to add comments? Honestly I don't think we're going to get a 'comment mechanism' on the existing site. It's static html generated from apt and other sources. However, getting plugin site -> wiki links is next on my list. Any thoughts on what a menu link on each plugin site might be called? For example, I'm planning to link Maven Javadoc Plugin http://maven.apache.org/plugins/maven-javadoc-plugin to its wiki page http://docs.codehaus.org/display/MAVENUSER/Javadoc+Plugin Just "Wiki" seems insufficient (especially since there's already a "Wiki" link on the main Maven site that points to the top of the MAVENUSER space.) The wiki still needs some organization, especially to make it easy to add new pages. The longer someone is unsure of what to click, the higher the probability that they'll just go away without contributing. Here's an interesting new contribution, a howto with screen shots of setting up Maven, Continuum and Archiva in a corporate environment: http://docs.codehaus.org/display/MAVENUSER/MavenProjectServer Someone on IRC mentioned writing a 'wikibook' (an open-content textbook) on Maven. There were several other suggestions that I haven't yet had time to sort through. Thanks for bringing it up again! More comments and discussion are welcome... -- Wendy - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Maven rant
Just wanted to dredge up this old thread concerning documentation to find out what status it has now after the last conversation. I had problems today finding some documentation on the war plugin. Pretty standard stuff but I couldn't even find the plugins documentation start page in the left-hand menu, rather I found it on the home page (where I happened NOT to be to start with) in the text. I think this is a symptom of the extensive nature of the maven docs, but still it's pretty fundamental. Secondly the comments functionality or the link to the wiki is a pretty urgent requirement for me, and I think I'm a typical user. I noticed recently that the www.springframework.org website uses drupal for its comments mechanism and that they have currently disabled it pending an upgrade to prevent comment-spamming! Having said that, I know it would be good if I could contribute but time constraints prevent that, sorry. I'm just hoping that re-iterating my comments will help get this issue further up the list of priorities, which I think would be beneficial for everybody. Regards Adam Sebastien Arbogast wrote: 2 thoughts about what you wrote Vincent: I totally agree on the fact that a few people have to write the core of the documentation before any community effort can be considered. But at some point, a PDF and an errata page is not the best way to create a community effort in order to keep this book up-to-date and more accessible. This leads me to the second point: Maven's wiki doesn't work for the very same reason Cocoon one didn't, for the very same reason I've never seen one good documentation effort based solely on a WIKI: no structure! And that's exactly what your book could be useful as: some sort of a spinal cord on which other content can be aggregated and accumulated over time, and sometimes assimilated on a rewrite. Moreover, I don't believe in Wikis at all because instead of adding some information, it just replaces it, even if it keeps some kind of version tracking behind the scenes. IMHO, Maven documentation should look like that: http://drupal.org/handbooks - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Maven rant
On 10/31/06, Jeff Mutonho <[EMAIL PROTECTED]> wrote: documents say.That led me to http://maven.apache.org/wagon/ and clicking on the Getting Started link I ended up at the URL http://maven.apache.org/wagon/guides/getting-started/index.html , and almost every link there leads to a : = Page Not Found You touched off a nice discussion, but it doesn't look like anyone fixed the broken links yet. I'm having trouble generating the wagon site, so I've posted a question on the development list. I also asked about the 'don't report broken links' advice in the 404 page, and it turns out that there is no automated link checking at the moment. We'll get that corrected to encourage people to report them. To that end, please feel free to open a JIRA issue for the problems with the links on the wagon site menu. :) Thanks, -- Wendy - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Maven rant
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
Re: Maven rant
On 11/5/06, David Whitehurst <[EMAIL PROTECTED]> wrote: I WIKI everything and I wish I had a public WIKI to write in that I felt comfortable that would stay there for all to see and wouldn't change. That's not really the nature of wikis... people will come along and edit what you've written. In Maven's case, sometimes things get moved from the wiki into the "official" documentation, especially plugin configuration examples. http://docs.codehaus.org/display/MAVENUSER/Home I'm new here, but this is like going to church and the message is always "this is how we do things here". It's a community or gathering and if it's not comfortable to speak up and say I have something to say, then it's not a public thing. I'm not really sure what you mean here. There's a lot of 'convention over configuration' in Maven, so there *is* a lot of "this is how we do things here". Source code goes in src/main/java, test code in src/main/test. Yes, you _can_ put it elsewhere if you insist, but we're not necessarily going to agree that it's a good idea. I agree with you because it's not easy to figure out how to get involved. Also, a portion or area of the server was out yesterday beause of a bug and it was very difficult for me to determine if this was a ditched effort or that someone was keeping the public away from something until a problem was fixed. Now I'm really confused. What happened? If a server was down, there's more than likely a fairly mundane reason for it. So when the WIKI opens up for assistance, let me know because I'm ready to share my notes. E.g. once I find out how to build plugins and debug them easily, I'll document everything. And, do I keep this for myself or does the community want my notes? Dennis already pointed out the MAVENUSER space, where everyone is welcome to contribute: http://docs.codehaus.org/display/MAVENUSER/Home -- Wendy - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Maven rant
David Whitehurst wrote: Excellent thoughts! I want to adopt maven2 and in-fact we are debating the issue at work. And the cons are the lack of documentation and the fact that ANT is easier to customize. And, that's what we all do, customize everything to support our needs. I WIKI everything and I wish I had a public WIKI to write in that I felt comfortable that would stay there for all to see and wouldn't change. So, what we need is the maven folks (whomever's in charge) to open a WIKI and leave it alone. There is already a wiki available where users are most welcome to contribute: http://docs.codehaus.org/display/MAVENUSER/Home -- Dennis Lundberg - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Maven rant
Excellent thoughts! I want to adopt maven2 and in-fact we are debating the issue at work. And the cons are the lack of documentation and the fact that ANT is easier to customize. And, that's what we all do, customize everything to support our needs. I WIKI everything and I wish I had a public WIKI to write in that I felt comfortable that would stay there for all to see and wouldn't change. So, what we need is the maven folks (whomever's in charge) to open a WIKI and leave it alone. I think that maven:site is fine for projects outside of maven and those that someone wants to play webmaster. But, the Maven site should be more open and if we get folks that provide wrong documentation, then boot them or remove their submissions (moderate). I'm new here, but this is like going to church and the message is always "this is how we do things here". It's a community or gathering and if it's not comfortable to speak up and say I have something to say, then it's not a public thing. I agree with you because it's not easy to figure out how to get involved. Also, a portion or area of the server was out yesterday beause of a bug and it was very difficult for me to determine if this was a ditched effort or that someone was keeping the public away from something until a problem was fixed. So when the WIKI opens up for assistance, let me know because I'm ready to share my notes. E.g. once I find out how to build plugins and debug them easily, I'll document everything. And, do I keep this for myself or does the community want my notes? I started a book for a publisher and didn't finish it due to timing, but I do have a chapter that clearly describes the installation and daemonizing and windows service installation for JBoss. Should I keep this since I didn't get published for sale? Or should I share it? I want to share it, but I can't host from my house due to my ISP setup. If I had a public hosting, I would drop it there immediately. I hope folks speak up to your email because I wholeheartedly agree. I do think, to speak for the Maven "boys" that everyone just wants things to be permanent and standard. And, that's very difficult to sustain I imagine. Good email, David On 11/5/06, franz see <[EMAIL PROTECTED]> wrote: 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
Re: Maven rant
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 simila
Re: Maven rant
+1 this is a fantastic idea.. would it take the form of an elaboration on the mvn site plugin? I propose that, at the lowest level, a test asserting that javadoc containing more than the default @author and @return tags in the javadoc for methods that arent property accessor/mutators would ensure most code is documented. then, if the test is met, the javadocs can be considered 'present'. Naturally there are any number of other tests... This would be the easiest level of compliance with the edict ( all code must be documented). Naturally, the site generated for the artifact woud provide the higher level overivew of the code thats much needed when diving into something... I propose perhaps a new type of doc format could be created / employed by the site plugin. src/site/wiki, or somehting like that. this would be content that once processed by the plugin would be entered into a known wikis (configurable in the pom) database which itself is editable/annotatable.. somehow the docs might be synced with this wiki.. or something... This would allow the structure of the wiki/documentation to spring forth from the code and the developers where the knowledge is cached. it would also allow coupling/interaction between the javadocs/reports and the documentation. But once that basic structure is set up, it would easily migrate to an interactive community driven format. the wiki would facilitate comments. the plugin might even read the wiki db and restore the comments into the documentation or something... These are all just proposals, as I wonder what this sort of solution might look like. Josh On 11/3/06, [EMAIL PROTECTED] < [EMAIL PROTECTED]> wrote: +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 >
RE: Maven rant
+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 p
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-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 ques
Re: Maven rant
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
Re: Maven rant
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]
Re: Maven rant
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]
Re: Maven rant
On 11/2/06, Mykel Alvis <[EMAIL PROTECTED]> wrote: Like it or not, people read a lot of wikis, but rarely write to them. They WILL, however, provide their comments from the peanut gallery on a mailing list. I'm currently looking at 1212 unread messages in my inbox from this list. That's from the last few weeks when I've been swamped with work and haven't had time to even go through the list to cull possible useful information. Ahhh... but *some* people will use the wiki, once they know it exists. If a bunch of people write on the mailing list, and several people collect and organize that on the wiki, then we've got something. (The final step, of pulling that information into the "official" documentation, isn't as important IMO. I consider the wiki a first class citizen of the documentation, and would rather leave information in a place where it can easily be updated.) Note that I'm firmly in the "Docs need to be better" crowd now. Since my religion demands that I take responsibility for my life, I guess that means that once I post this, I've got to go to the Maven user wiki and start doing updates. Anyone else that feels like it is welcome to join me there. Welcome! -- Wendy - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Maven rant
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. Earlier, I asked, "Any ideas on how to present that as an option? What would the menu link be called? How should the pages on the wiki be organized?" As for when... I'm booked for a couple more weeks, but have set aside some time for this in mid-November if no one has gotten to it by then. I'm talking about the 'getting the links on the plugin sites' part -- the wiki is of course already open to anyone who would like to contribute. -- Wendy - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Maven rant
My $0.02: First of all, lets note that I make most of my livelihood working on maven builds, so this is not (repeat NOT) criticism of the product, developers, or community at large. The maven users list (and the associted developers lists and users lists for all the OTHER not-necessarily-maven-specific-but-used-by-practically-nobody-else stuff, like wagon) are currently the only way data gets shared.Like it or not, people read a lot of wikis, but rarely write to them. They WILL, however, provide their comments from the peanut gallery on a mailing list. I'm currently looking at 1212 unread messages in my inbox from this list. That's from the last few weeks when I've been swamped with work and haven't had time to even go through the list to cull possible useful information. Nobody, least of all me, expects people who write software for free to ALSO do everything ELSE associated with the software. Unfortunately, in the case of of the maven suite (maven/plexus/wagon/cargo/doxia/archiva/etc), it's practically impossible for anyone else to do anything. The core team, whose membership I'm a little fuzzy on at the moment, has a lot of the "how to do thing X" locked up in one of several places: 1. The existent site docs. The guides are good, but pretty weak in a number of places 2. The Mergere book. This thing is the only, and I do mean only, reason that I was able to develop anything more than the simplest of plugins. 3. This list, which I hold in Gmail and use searches on every time I have a problem. But frankly, this list is often like a group at a coffee shop. There's a lot of "I need" requests (like this thread is) and a lot of "Me, too" responses, and far fewer "HOWTO" responses. and mostly 4. Inside people's heads. This is where a lot of useful stuff lives, not just in OSS but in everyday life. And writing what you know (or more probably what you THINK you know) down for everyone to cut to shreds evokes human fears by the droves. Ergo, people usually don't do it. Fact: Signal to noise on the maven lists is pretty low. Fact: The reason this ratio is low is because much of the signal comes in the form of HOWTOs for extremely simple problems Fact: N00bs need docs. Ignoring the asshats that dive into something as complex as maven and want to be hand-held through the process, most newbies can glean essential information by reading. Opinion: Docs need improving. If a lot of the basic documentation for maven were somewhat improved as an overall effort BY ALL OF US, the signal would go up because the list would be where we discussed and vetted real problems instead of "How do I get started" questions. Note that I'm firmly in the "Docs need to be better" crowd now. Since my religion demands that I take responsibility for my life, I guess that means that once I post this, I've got to go to the Maven user wiki and start doing updates. Anyone else that feels like it is welcome to join me there. -- I'm just an unfrozen caveman software developer. I don't understand your strange, "modern" ways.
RE: Maven rant
What I meant by "it" was the comment mechanism. Sebastien -Original Message- From: Wendy Smoak [mailto:[EMAIL PROTECTED] Sent: Thursday, November 02, 2006 3:35 PM To: Maven Users List Subject: Re: Maven rant On 11/2/06, Sebastien Brunot <[EMAIL PROTECTED]> wrote: > Good ! When do you think it would be possible to have it online ? Have what online? We need to decide what "it" is first. :) What we have available is all of Maven's documentation, (some of which is generated, some is in APT format,) and the MAVENUSER wiki space. Currently, the only connection between the two is the 'User Contributed' link on the main site menu. How do you see this working? -- Wendy - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Maven rant
What I'd like to do for comments is make use of the MAVENUSER wiki [1]. I'd like to see a link on every plugin site so that users can share configuration examples or tell us that something is just plain wrong. +1 to that
Re: Maven rant
On 11/2/06, Sebastien Brunot <[EMAIL PROTECTED]> wrote: Good ! When do you think it would be possible to have it online ? Have what online? We need to decide what "it" is first. :) What we have available is all of Maven's documentation, (some of which is generated, some is in APT format,) and the MAVENUSER wiki space. Currently, the only connection between the two is the 'User Contributed' link on the main site menu. How do you see this working? -- Wendy - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
RE: Maven rant
Good ! When do you think it would be possible to have it online ? Sebastien -Original Message- From: Adam Hardy [mailto:[EMAIL PROTECTED] Sent: Thursday, November 02, 2006 11:44 AM To: Maven Users List Subject: Re: Maven rant Wendy Smoak wrote: > On 10/31/06, Sebastien Arbogast <[EMAIL PROTECTED]> wrote: > >> Think of Hibernate or PHP documentation: one base reference book with >> DYNAMIC comments in which people can share their thoughts and >> experiences about each feature/chapter, remarks that can be later >> integrated when the reference is rewritten. The problem is that, >> whereas development itself is a highly-collaborative and efficient >> process, nothing is really done so that documentation writing is >> collaborative enough: no workflow, no direct input, no dynamic >> comments, etc. > > Many of the plugins have improved docs that haven't been published > yet. That's on my list for this weekend, determining whether it's > okay to publish them, or whether we need to establish a separate area > for the latest-and-greatest docs that may not match the released > version. > > What I'd like to do for comments is make use of the MAVENUSER wiki > [1]. I'd like to see a link on every plugin site so that users can > share configuration examples or tell us that something is just plain > wrong. > > What do you think? Any ideas on how to present that as an option? > What would the menu link be called? How should the pages on the wiki > be organized? > > (The Better Builds book belongs to Mergere, so they would have to > agree to any changes in the way it is produced.) > > [1] http://docs.codehaus.org/display/MAVENUSER/Home I think the comments-based approach is the best option. Users can post examples that work. Authors can improve the documentation really easily, taking on board comments. An indication of the page's documentation quality would be the amount of newby questions just asking what to do. Gaps in the documentation would also be identified quickly by users. I think it is by far the most agile approach to documentation. Adam - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Maven rant
Wendy Smoak wrote: On 10/31/06, Sebastien Arbogast <[EMAIL PROTECTED]> wrote: Think of Hibernate or PHP documentation: one base reference book with DYNAMIC comments in which people can share their thoughts and experiences about each feature/chapter, remarks that can be later integrated when the reference is rewritten. The problem is that, whereas development itself is a highly-collaborative and efficient process, nothing is really done so that documentation writing is collaborative enough: no workflow, no direct input, no dynamic comments, etc. Many of the plugins have improved docs that haven't been published yet. That's on my list for this weekend, determining whether it's okay to publish them, or whether we need to establish a separate area for the latest-and-greatest docs that may not match the released version. What I'd like to do for comments is make use of the MAVENUSER wiki [1]. I'd like to see a link on every plugin site so that users can share configuration examples or tell us that something is just plain wrong. What do you think? Any ideas on how to present that as an option? What would the menu link be called? How should the pages on the wiki be organized? (The Better Builds book belongs to Mergere, so they would have to agree to any changes in the way it is produced.) [1] http://docs.codehaus.org/display/MAVENUSER/Home I think the comments-based approach is the best option. Users can post examples that work. Authors can improve the documentation really easily, taking on board comments. An indication of the page's documentation quality would be the amount of newby questions just asking what to do. Gaps in the documentation would also be identified quickly by users. I think it is by far the most agile approach to documentation. Adam - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
RE: Maven rant
I agree that the problem may be faced, but what about trying it the agile way : just putting everything online in a new wiki instance, and waiting a few month to see which how it evolves ? Sebastien (the other one ;-) -Original Message- From: Sebastien Arbogast [mailto:[EMAIL PROTECTED] Sent: Thursday, November 02, 2006 10:31 AM To: Maven Users List Subject: Re: Maven rant But you won't solve the main issue of a wiki system: information replacement. I still think that a comment system would be more reliable on the long term. 2006/11/2, Sebastien Brunot <[EMAIL PROTECTED]>: > I'm just joining, but what about creating a wiki with the entire free maven > book content so that the (user) community can update it ? I agree to the fact > that you need some predefined structure to ensure effective documentation by > users / developers. Adding a snipet of documentation should be a "no cost" > operation, and having a predefined structure may help to achieve this goal. > > Sebastien > > -Original Message- > From: Sebastien Arbogast [mailto:[EMAIL PROTECTED] > Sent: Tuesday, October 31, 2006 2:45 PM > To: Maven Users List > Subject: Re: Maven rant > > 2 thoughts about what you wrote Vincent: > > I totally agree on the fact that a few people have to write the core of the > documentation before any community effort can be considered. > But at some point, a PDF and an errata page is not the best way to create a > community effort in order to keep this book up-to-date and more accessible. > > This leads me to the second point: Maven's wiki doesn't work for the very > same reason Cocoon one didn't, for the very same reason I've never seen one > good documentation effort based solely on a WIKI: no structure! And that's > exactly what your book could be useful as: some sort of a spinal cord on > which other content can be aggregated and accumulated over time, and > sometimes assimilated on a rewrite. > Moreover, I don't believe in Wikis at all because instead of adding some > information, it just replaces it, even if it keeps some kind of version > tracking behind the scenes. > > IMHO, Maven documentation should look like that: > http://drupal.org/handbooks > > 2006/10/31, Vincent Massol <[EMAIL PROTECTED]>: > > > > > > > -Original Message- > > > From: Sebastien Arbogast [mailto:[EMAIL PROTECTED] > > > Sent: mardi 31 octobre 2006 14:18 > > > To: Maven Users List > > > Subject: Re: Maven rant > > > > > > I totally agree but I think that the problem is very difficult to > > > solve, especially with all the incredible amount of undeocumented > > > features that Maven has. Moreover, the problem is amplified by the > > > fact that Maven allows the generation of most of the documentation: > > > but if you don't write it, it won't write itself, so you will > > > endup with dead links everywhere. > > > > > > As I see it, the problem in most Open Source projects is that > > > developers do that on their free time, and developers aren't writers: > > > those are two completely different tasks and the second one is not > > > the most enjoyable. > > > > > > And last but not least: Open Source software is highly evolutive: > > > why bother write some documentation for a feature that can be > > > replaced by something more interesting in no-time and without any > > > possible anticipation. > > > > > > The thing is that Maven is not the first Maven project I work with > > > which faces that very issue. I had exactly the same problems a few > > > months ago with Cocoon guys, and my remark is still the same: why > > > do project leaders keep on considering documentation as a static thing. > > > Think of Hibernate or PHP documentation: one base reference book > > > with DYNAMIC comments in which people can share their thoughts and > > > experiences about each feature/chapter, remarks that can be later > > > integrated when the reference is rewritten. The problem is that, > > > whereas development itself is a highly-collaborative and efficient > > > process, nothing is really done so that documentation writing is > > > collaborative enough: no workflow, no direct input, no dynamic > > > comments, etc. Think of it: "Better Builds With Maven" is the most > > > comprehensive documentation about Maven2. But was it written > > > collaboratively? No. And I'm convinced that if it had been, it > > > would be much higher quality and much more acc
Re: Maven rant
But you won't solve the main issue of a wiki system: information replacement. I still think that a comment system would be more reliable on the long term. 2006/11/2, Sebastien Brunot <[EMAIL PROTECTED]>: I'm just joining, but what about creating a wiki with the entire free maven book content so that the (user) community can update it ? I agree to the fact that you need some predefined structure to ensure effective documentation by users / developers. Adding a snipet of documentation should be a "no cost" operation, and having a predefined structure may help to achieve this goal. Sebastien -Original Message- From: Sebastien Arbogast [mailto:[EMAIL PROTECTED] Sent: Tuesday, October 31, 2006 2:45 PM To: Maven Users List Subject: Re: Maven rant 2 thoughts about what you wrote Vincent: I totally agree on the fact that a few people have to write the core of the documentation before any community effort can be considered. But at some point, a PDF and an errata page is not the best way to create a community effort in order to keep this book up-to-date and more accessible. This leads me to the second point: Maven's wiki doesn't work for the very same reason Cocoon one didn't, for the very same reason I've never seen one good documentation effort based solely on a WIKI: no structure! And that's exactly what your book could be useful as: some sort of a spinal cord on which other content can be aggregated and accumulated over time, and sometimes assimilated on a rewrite. Moreover, I don't believe in Wikis at all because instead of adding some information, it just replaces it, even if it keeps some kind of version tracking behind the scenes. IMHO, Maven documentation should look like that: http://drupal.org/handbooks 2006/10/31, Vincent Massol <[EMAIL PROTECTED]>: > > > > -Original Message- > > From: Sebastien Arbogast [mailto:[EMAIL PROTECTED] > > Sent: mardi 31 octobre 2006 14:18 > > To: Maven Users List > > Subject: Re: Maven rant > > > > I totally agree but I think that the problem is very difficult to > > solve, especially with all the incredible amount of undeocumented > > features that Maven has. Moreover, the problem is amplified by the > > fact that Maven allows the generation of most of the documentation: > > but if you don't write it, it won't write itself, so you will endup > > with dead links everywhere. > > > > As I see it, the problem in most Open Source projects is that > > developers do that on their free time, and developers aren't writers: > > those are two completely different tasks and the second one is not > > the most enjoyable. > > > > And last but not least: Open Source software is highly evolutive: > > why bother write some documentation for a feature that can be > > replaced by something more interesting in no-time and without any > > possible anticipation. > > > > The thing is that Maven is not the first Maven project I work with > > which faces that very issue. I had exactly the same problems a few > > months ago with Cocoon guys, and my remark is still the same: why do > > project leaders keep on considering documentation as a static thing. > > Think of Hibernate or PHP documentation: one base reference book > > with DYNAMIC comments in which people can share their thoughts and > > experiences about each feature/chapter, remarks that can be later > > integrated when the reference is rewritten. The problem is that, > > whereas development itself is a highly-collaborative and efficient > > process, nothing is really done so that documentation writing is > > collaborative enough: no workflow, no direct input, no dynamic > > comments, etc. Think of it: "Better Builds With Maven" is the most > > comprehensive documentation about Maven2. But was it written > > collaboratively? No. And I'm convinced that if it had been, it would > > be much higher quality and much more accessible today. > > Sebastien, I don't believe this is true. This is the same as any open > source project. It's not the community that creates an open source > project. It's one or two guys (possibly 3 ;-)). Then once there is a > strong kernel developed by these few guys then others will join and > help. The same is true for documentation. You need one or 2 leaders to first write the core of it. > This is what we've done with BBWM. Now I agree that a good idea could > be to build on it by opening it up to the community. But don't believe > a single instant that the community will write a good quality book by > itself. BTW there's already a Maven wiki which is opened to anyone > interested. It's been
RE: Maven rant
> -Original Message- > From: Sebastien Brunot [mailto:[EMAIL PROTECTED] > Sent: jeudi 2 novembre 2006 10:26 > To: Maven Users List > Subject: RE: Maven rant > > I'm just joining, but what about creating a wiki with the entire free > maven book content so that the (user) community can update it ? I agree > to the fact that you need some predefined structure to ensure effective > documentation by users / developers. Adding a snipet of documentation > should be a "no cost" operation, and having a predefined structure may > help to achieve this goal. This would be good but it's a choice to be made by Mergere (the publisher of the book). Thanks -Vincent > -Original Message- > From: Sebastien Arbogast [mailto:[EMAIL PROTECTED] > Sent: Tuesday, October 31, 2006 2:45 PM > To: Maven Users List > Subject: Re: Maven rant > > 2 thoughts about what you wrote Vincent: > > I totally agree on the fact that a few people have to write the core of > the documentation before any community effort can be considered. > But at some point, a PDF and an errata page is not the best way to > create a community effort in order to keep this book up-to-date and > more accessible. > > This leads me to the second point: Maven's wiki doesn't work for the > very same reason Cocoon one didn't, for the very same reason I've never > seen one good documentation effort based solely on a WIKI: no > structure! And that's exactly what your book could be useful as: some > sort of a spinal cord on which other content can be aggregated and > accumulated over time, and sometimes assimilated on a rewrite. > Moreover, I don't believe in Wikis at all because instead of adding > some information, it just replaces it, even if it keeps some kind of > version tracking behind the scenes. > > IMHO, Maven documentation should look like that: > http://drupal.org/handbooks > > 2006/10/31, Vincent Massol <[EMAIL PROTECTED]>: > > > > > > > -Original Message- > > > From: Sebastien Arbogast [mailto:[EMAIL PROTECTED] > > > Sent: mardi 31 octobre 2006 14:18 > > > To: Maven Users List > > > Subject: Re: Maven rant > > > > > > I totally agree but I think that the problem is very difficult to > > > solve, especially with all the incredible amount of undeocumented > > > features that Maven has. Moreover, the problem is amplified by the > > > fact that Maven allows the generation of most of the documentation: > > > but if you don't write it, it won't write itself, so you will endup > > > with dead links everywhere. > > > > > > As I see it, the problem in most Open Source projects is that > > > developers do that on their free time, and developers aren't > writers: > > > those are two completely different tasks and the second one is not > > > the most enjoyable. > > > > > > And last but not least: Open Source software is highly evolutive: > > > why bother write some documentation for a feature that can be > > > replaced by something more interesting in no-time and without any > > > possible anticipation. > > > > > > The thing is that Maven is not the first Maven project I work with > > > which faces that very issue. I had exactly the same problems a few > > > months ago with Cocoon guys, and my remark is still the same: why > do > > > project leaders keep on considering documentation as a static > thing. > > > Think of Hibernate or PHP documentation: one base reference book > > > with DYNAMIC comments in which people can share their thoughts and > > > experiences about each feature/chapter, remarks that can be later > > > integrated when the reference is rewritten. The problem is that, > > > whereas development itself is a highly-collaborative and efficient > > > process, nothing is really done so that documentation writing is > > > collaborative enough: no workflow, no direct input, no dynamic > > > comments, etc. Think of it: "Better Builds With Maven" is the most > > > comprehensive documentation about Maven2. But was it written > > > collaboratively? No. And I'm convinced that if it had been, it > would > > > be much higher quality and much more accessible today. > > > > Sebastien, I don't believe this is true. This is the same as any open > > source project. It's not the community that creates an open source > > project. It's one or two guys (possibly 3 ;-)). Then once there is a > > strong kernel developed by these few guys th
RE: Maven rant
I'm just joining, but what about creating a wiki with the entire free maven book content so that the (user) community can update it ? I agree to the fact that you need some predefined structure to ensure effective documentation by users / developers. Adding a snipet of documentation should be a "no cost" operation, and having a predefined structure may help to achieve this goal. Sebastien -Original Message- From: Sebastien Arbogast [mailto:[EMAIL PROTECTED] Sent: Tuesday, October 31, 2006 2:45 PM To: Maven Users List Subject: Re: Maven rant 2 thoughts about what you wrote Vincent: I totally agree on the fact that a few people have to write the core of the documentation before any community effort can be considered. But at some point, a PDF and an errata page is not the best way to create a community effort in order to keep this book up-to-date and more accessible. This leads me to the second point: Maven's wiki doesn't work for the very same reason Cocoon one didn't, for the very same reason I've never seen one good documentation effort based solely on a WIKI: no structure! And that's exactly what your book could be useful as: some sort of a spinal cord on which other content can be aggregated and accumulated over time, and sometimes assimilated on a rewrite. Moreover, I don't believe in Wikis at all because instead of adding some information, it just replaces it, even if it keeps some kind of version tracking behind the scenes. IMHO, Maven documentation should look like that: http://drupal.org/handbooks 2006/10/31, Vincent Massol <[EMAIL PROTECTED]>: > > > > -Original Message- > > From: Sebastien Arbogast [mailto:[EMAIL PROTECTED] > > Sent: mardi 31 octobre 2006 14:18 > > To: Maven Users List > > Subject: Re: Maven rant > > > > I totally agree but I think that the problem is very difficult to > > solve, especially with all the incredible amount of undeocumented > > features that Maven has. Moreover, the problem is amplified by the > > fact that Maven allows the generation of most of the documentation: > > but if you don't write it, it won't write itself, so you will endup > > with dead links everywhere. > > > > As I see it, the problem in most Open Source projects is that > > developers do that on their free time, and developers aren't writers: > > those are two completely different tasks and the second one is not > > the most enjoyable. > > > > And last but not least: Open Source software is highly evolutive: > > why bother write some documentation for a feature that can be > > replaced by something more interesting in no-time and without any > > possible anticipation. > > > > The thing is that Maven is not the first Maven project I work with > > which faces that very issue. I had exactly the same problems a few > > months ago with Cocoon guys, and my remark is still the same: why do > > project leaders keep on considering documentation as a static thing. > > Think of Hibernate or PHP documentation: one base reference book > > with DYNAMIC comments in which people can share their thoughts and > > experiences about each feature/chapter, remarks that can be later > > integrated when the reference is rewritten. The problem is that, > > whereas development itself is a highly-collaborative and efficient > > process, nothing is really done so that documentation writing is > > collaborative enough: no workflow, no direct input, no dynamic > > comments, etc. Think of it: "Better Builds With Maven" is the most > > comprehensive documentation about Maven2. But was it written > > collaboratively? No. And I'm convinced that if it had been, it would > > be much higher quality and much more accessible today. > > Sebastien, I don't believe this is true. This is the same as any open > source project. It's not the community that creates an open source > project. It's one or two guys (possibly 3 ;-)). Then once there is a > strong kernel developed by these few guys then others will join and > help. The same is true for documentation. You need one or 2 leaders to first > write the core of it. > This is what we've done with BBWM. Now I agree that a good idea could > be to build on it by opening it up to the community. But don't believe > a single instant that the community will write a good quality book by > itself. BTW there's already a Maven wiki which is opened to anyone > interested. It's been there for more than a year but I wouldn't call > the result comprehensive documentation. > > Thanks > -Vincent > > > 2006/10/31, dhoffer <[EMAIL PROT
Re: Maven rant
"Wayne Fay" <[EMAIL PROTECTED]> writes: > The "Documentation Check" (DOCCK) plugin was recently created to help > address this very issue. It will help not only Maven but also its > plugins and even other projects/plugins using Maven. > Hello to all, And first great thanks to all maven developers and contributors for creating this really fascinating tool. I have been using maven 1.x and 2.z for about three now I think, in the beginning casually then on a regular basis for later projects (and when maven 2.0 was released). I have written plugins, filed one or two Jira issues, contributed to the best of my ability to MLs, started some discussions about maven reporting. I even use maven to generate my site and use custom skins (BTW, something painful given that you have to use such awful things as Velocity. My apologies to any Velocity team member lurking around there :-)), and tried writing a custom extension for doxia. I would be more than happy to contribute further but there are major issues I have been facing: 1. time is lacking to undertake the kind of things I would like to see in maven 2. development documentation is well below any standard Point 1 is beyond control, but other point deserve some explanations. As an example, take the class org.apache.maven.doxia.siterenderer.DefaultSiteRenderer. This class is responsible for the whole site generation process in doxia (and then maven) and there are about ten lines of comments in it (500 lines of code). Neither in the interface Renderer it implements. I am not particulary proud of my coding abilities and would certainly not rank among top level coders in any contest, but I know two things for sure about software engineering: write comments where they are useful, write thorough unit tests to further document and assert the quality of your the code (and your understanding of th erequirements). This have hurt me when I tried to extend Doxia with a new module. I am not of course pointing at anyone in particular, as this state of affair is really common in all maven code fragments I have seen. But when you add poor code documentation to no user documentation... Last but not least, I follow Jeff Muntunho in his rant when he says that support from developers is rather scarce. I know that open source is a harsh mistress and I am sure this is not a willingful attitude, but it is sometimes discouraging not to have answers from those who know. my 50 cents, -- Arnaud Bailly, PhD. OQube < software engineering \ génie logiciel > \web> http://www.oqube.com - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Maven rant
The "Documentation Check" (DOCCK) plugin was recently created to help address this very issue. It will help not only Maven but also its plugins and even other projects/plugins using Maven. Maven Dev has established a baseline for expected documentation and will now use this plugin to enforce that baseline for all plugins etc. This doesn't help much if other Plugin sites (ie Codehaus) don't adopt the plugin into their process too, or if you're looking to use a random plugin created and hosted entirely independent of Maven, but it should help alleviate this issue for many plugins. Wayne On 10/31/06, Wendy Smoak <[EMAIL PROTECTED]> wrote: On 10/31/06, Sebastien Arbogast <[EMAIL PROTECTED]> wrote: > Think of Hibernate or PHP documentation: one base reference book with > DYNAMIC comments in which people can share their thoughts and > experiences about each feature/chapter, remarks that can be later > integrated when the reference is rewritten. The problem is that, > whereas development itself is a highly-collaborative and efficient > process, nothing is really done so that documentation writing is > collaborative enough: no workflow, no direct input, no dynamic > comments, etc. Many of the plugins have improved docs that haven't been published yet. That's on my list for this weekend, determining whether it's okay to publish them, or whether we need to establish a separate area for the latest-and-greatest docs that may not match the released version. What I'd like to do for comments is make use of the MAVENUSER wiki [1]. I'd like to see a link on every plugin site so that users can share configuration examples or tell us that something is just plain wrong. What do you think? Any ideas on how to present that as an option? What would the menu link be called? How should the pages on the wiki be organized? (The Better Builds book belongs to Mergere, so they would have to agree to any changes in the way it is produced.) [1] http://docs.codehaus.org/display/MAVENUSER/Home -- Wendy - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Maven rant
On 10/31/06, Sebastien Arbogast <[EMAIL PROTECTED]> wrote: Think of Hibernate or PHP documentation: one base reference book with DYNAMIC comments in which people can share their thoughts and experiences about each feature/chapter, remarks that can be later integrated when the reference is rewritten. The problem is that, whereas development itself is a highly-collaborative and efficient process, nothing is really done so that documentation writing is collaborative enough: no workflow, no direct input, no dynamic comments, etc. Many of the plugins have improved docs that haven't been published yet. That's on my list for this weekend, determining whether it's okay to publish them, or whether we need to establish a separate area for the latest-and-greatest docs that may not match the released version. What I'd like to do for comments is make use of the MAVENUSER wiki [1]. I'd like to see a link on every plugin site so that users can share configuration examples or tell us that something is just plain wrong. What do you think? Any ideas on how to present that as an option? What would the menu link be called? How should the pages on the wiki be organized? (The Better Builds book belongs to Mergere, so they would have to agree to any changes in the way it is produced.) [1] http://docs.codehaus.org/display/MAVENUSER/Home -- Wendy - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Maven rant
On 10/31/06, Vincent Massol <[EMAIL PROTECTED]> wrote: BTW there's already a Maven wiki which is opened to anyone interested. It's been there for more than a year but I wouldn't call the result comprehensive documentation. Thanks -Vincent I'm sure there are many people who might want to contribute but its almost impossible to make valuable contribution when one does not the knowledge. I do appreciate the fact that as developers we hate documentation or we might not even be good at it , but is it such a hard task to put a few lines that say ..."This plugin does this and that , and here's one or two examples of how to use itThe other flags or options that you can play with are this and that...blah blah" .How hard is that?If I wrote a plugin I would do my best to inform people how use it and prevent them from getting trapped in quagmires of endless hours trying to figure out the most of the basic things a plugin can do. Jeff Mutonho GoogleTalk : ejbengine Skype: ejbengine Registered Linux user number 366042 - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Maven rant
2 thoughts about what you wrote Vincent: I totally agree on the fact that a few people have to write the core of the documentation before any community effort can be considered. But at some point, a PDF and an errata page is not the best way to create a community effort in order to keep this book up-to-date and more accessible. This leads me to the second point: Maven's wiki doesn't work for the very same reason Cocoon one didn't, for the very same reason I've never seen one good documentation effort based solely on a WIKI: no structure! And that's exactly what your book could be useful as: some sort of a spinal cord on which other content can be aggregated and accumulated over time, and sometimes assimilated on a rewrite. Moreover, I don't believe in Wikis at all because instead of adding some information, it just replaces it, even if it keeps some kind of version tracking behind the scenes. IMHO, Maven documentation should look like that: http://drupal.org/handbooks 2006/10/31, Vincent Massol <[EMAIL PROTECTED]>: > -Original Message- > From: Sebastien Arbogast [mailto:[EMAIL PROTECTED] > Sent: mardi 31 octobre 2006 14:18 > To: Maven Users List > Subject: Re: Maven rant > > I totally agree but I think that the problem is very difficult to > solve, especially with all the incredible amount of undeocumented > features that Maven has. Moreover, the problem is amplified by the > fact that Maven allows the generation of most of the documentation: > but if you don't write it, it won't write itself, so you will endup > with dead links everywhere. > > As I see it, the problem in most Open Source projects is that > developers do that on their free time, and developers aren't writers: > those are two completely different tasks and the second one is not the > most enjoyable. > > And last but not least: Open Source software is highly evolutive: why > bother write some documentation for a feature that can be replaced by > something more interesting in no-time and without any possible > anticipation. > > The thing is that Maven is not the first Maven project I work with > which faces that very issue. I had exactly the same problems a few > months ago with Cocoon guys, and my remark is still the same: why do > project leaders keep on considering documentation as a static thing. > Think of Hibernate or PHP documentation: one base reference book with > DYNAMIC comments in which people can share their thoughts and > experiences about each feature/chapter, remarks that can be later > integrated when the reference is rewritten. The problem is that, > whereas development itself is a highly-collaborative and efficient > process, nothing is really done so that documentation writing is > collaborative enough: no workflow, no direct input, no dynamic > comments, etc. Think of it: "Better Builds With Maven" is the most > comprehensive documentation about Maven2. But was it written > collaboratively? No. And I'm convinced that if it had been, it would > be much higher quality and much more accessible today. Sebastien, I don't believe this is true. This is the same as any open source project. It's not the community that creates an open source project. It's one or two guys (possibly 3 ;-)). Then once there is a strong kernel developed by these few guys then others will join and help. The same is true for documentation. You need one or 2 leaders to first write the core of it. This is what we've done with BBWM. Now I agree that a good idea could be to build on it by opening it up to the community. But don't believe a single instant that the community will write a good quality book by itself. BTW there's already a Maven wiki which is opened to anyone interested. It's been there for more than a year but I wouldn't call the result comprehensive documentation. Thanks -Vincent > 2006/10/31, dhoffer <[EMAIL PROTECTED]>: > > > > Jeff, > > > > I use maven and I really like it and I don't want this to sound like > > negative criticism but you are right, the learning curve for maven > newbie's > > is huge and there just isn't much good docs available. I have wound > up > > getting bits of pieces of info from here and there...it just takes so > long. > > It would be great if some maven gurus could solve this problem and > make > > maven more accessible. > > > > > > > > Jeff Mutonho wrote: > > > > > > Is maven in the process of unintentionally killing itself due to > poor > > > support and documentation?I may be wrong but I strongly feel that > the > > > poor support and documentation is hampering adoption of an > otherwise > > > brilliant tool.
Re: Maven rant
I think your right; I understand it's a hard problem to solve. That's way I'm not negative on maven; I just think it's a big issue that needs attention. The people that know this stuff, the developers that write maven probably aren't great documentation people or if they are just don't have the time. Is there a way that regular users, such as myself, can help? I'm neither a maven guru nor a web master...but once I understand something I could do a decent job of wordsmithing it. Sebastien Arbogast wrote: > > I totally agree but I think that the problem is very difficult to > solve, especially with all the incredible amount of undeocumented > features that Maven has. Moreover, the problem is amplified by the > fact that Maven allows the generation of most of the documentation: > but if you don't write it, it won't write itself, so you will endup > with dead links everywhere. > > As I see it, the problem in most Open Source projects is that > developers do that on their free time, and developers aren't writers: > those are two completely different tasks and the second one is not the > most enjoyable. > > And last but not least: Open Source software is highly evolutive: why > bother write some documentation for a feature that can be replaced by > something more interesting in no-time and without any possible > anticipation. > > The thing is that Maven is not the first Maven project I work with > which faces that very issue. I had exactly the same problems a few > months ago with Cocoon guys, and my remark is still the same: why do > project leaders keep on considering documentation as a static thing. > Think of Hibernate or PHP documentation: one base reference book with > DYNAMIC comments in which people can share their thoughts and > experiences about each feature/chapter, remarks that can be later > integrated when the reference is rewritten. The problem is that, > whereas development itself is a highly-collaborative and efficient > process, nothing is really done so that documentation writing is > collaborative enough: no workflow, no direct input, no dynamic > comments, etc. Think of it: "Better Builds With Maven" is the most > comprehensive documentation about Maven2. But was it written > collaboratively? No. And I'm convinced that if it had been, it would > be much higher quality and much more accessible today. > > Just my 2 cents. > > 2006/10/31, dhoffer <[EMAIL PROTECTED]>: >> >> Jeff, >> >> I use maven and I really like it and I don't want this to sound like >> negative criticism but you are right, the learning curve for maven >> newbie's >> is huge and there just isn't much good docs available. I have wound up >> getting bits of pieces of info from here and there...it just takes so >> long. >> It would be great if some maven gurus could solve this problem and make >> maven more accessible. >> >> >> >> Jeff Mutonho wrote: >> > >> > Is maven in the process of unintentionally killing itself due to poor >> > support and documentation?I may be wrong but I strongly feel that the >> > poor support and documentation is hampering adoption of an otherwise >> > brilliant tool.It always seems like the participation of plugin >> > developers in answering questions from mere users like myself is >> > non-existent.Then lets not forget the poor documentation.The BB book >> > was an excellent idea ,but sometimes it just does not address problems >> > users face on the "setup battle field" and the "configuration >> > trenches" we're all familiar with.I'll give an example that relates to >> > my experience.I posted questions relating to problems with the Maven >> > Wagon plugin and in the process also thought it wise to see what the >> > documents say.That led me to http://maven.apache.org/wagon/ and >> > clicking on the Getting Started link I ended up at the URL >> > http://maven.apache.org/wagon/guides/getting-started/index.html , and >> > almost every link there leads to a : >> > = >> > Page Not Found >> > Sorry, the page you requested was not found. This may because: >> > >> > * The page has moved, was outdated, or has not been created yet >> > * You typed the address incorrectly >> > * You following a link from another site that pointed to this page. >> > >> > We have recently reorganised our site, so please try looking in the >> > navigation on the left for the item you are looking for on Maven 1.x >> > or the Maven project. For information about Maven 2.0 or Continuum, >> > please visit their sub sites, available from the links in the top >> > right of the page. There is no need to report this broken link to the >> > Maven team, as errors are periodically monitored and repaired. >> > >> > === >> > >> > Same thing happens with the "Examples" link.Surely this cannot be a >> > pleasant user experience for anyone , let alone for a poor newbie who >> > might think lookin
RE: Maven rant
> -Original Message- > From: Sebastien Arbogast [mailto:[EMAIL PROTECTED] > Sent: mardi 31 octobre 2006 14:18 > To: Maven Users List > Subject: Re: Maven rant > > I totally agree but I think that the problem is very difficult to > solve, especially with all the incredible amount of undeocumented > features that Maven has. Moreover, the problem is amplified by the > fact that Maven allows the generation of most of the documentation: > but if you don't write it, it won't write itself, so you will endup > with dead links everywhere. > > As I see it, the problem in most Open Source projects is that > developers do that on their free time, and developers aren't writers: > those are two completely different tasks and the second one is not the > most enjoyable. > > And last but not least: Open Source software is highly evolutive: why > bother write some documentation for a feature that can be replaced by > something more interesting in no-time and without any possible > anticipation. > > The thing is that Maven is not the first Maven project I work with > which faces that very issue. I had exactly the same problems a few > months ago with Cocoon guys, and my remark is still the same: why do > project leaders keep on considering documentation as a static thing. > Think of Hibernate or PHP documentation: one base reference book with > DYNAMIC comments in which people can share their thoughts and > experiences about each feature/chapter, remarks that can be later > integrated when the reference is rewritten. The problem is that, > whereas development itself is a highly-collaborative and efficient > process, nothing is really done so that documentation writing is > collaborative enough: no workflow, no direct input, no dynamic > comments, etc. Think of it: "Better Builds With Maven" is the most > comprehensive documentation about Maven2. But was it written > collaboratively? No. And I'm convinced that if it had been, it would > be much higher quality and much more accessible today. Sebastien, I don't believe this is true. This is the same as any open source project. It's not the community that creates an open source project. It's one or two guys (possibly 3 ;-)). Then once there is a strong kernel developed by these few guys then others will join and help. The same is true for documentation. You need one or 2 leaders to first write the core of it. This is what we've done with BBWM. Now I agree that a good idea could be to build on it by opening it up to the community. But don't believe a single instant that the community will write a good quality book by itself. BTW there's already a Maven wiki which is opened to anyone interested. It's been there for more than a year but I wouldn't call the result comprehensive documentation. Thanks -Vincent > 2006/10/31, dhoffer <[EMAIL PROTECTED]>: > > > > Jeff, > > > > I use maven and I really like it and I don't want this to sound like > > negative criticism but you are right, the learning curve for maven > newbie's > > is huge and there just isn't much good docs available. I have wound > up > > getting bits of pieces of info from here and there...it just takes so > long. > > It would be great if some maven gurus could solve this problem and > make > > maven more accessible. > > > > > > > > Jeff Mutonho wrote: > > > > > > Is maven in the process of unintentionally killing itself due to > poor > > > support and documentation?I may be wrong but I strongly feel that > the > > > poor support and documentation is hampering adoption of an > otherwise > > > brilliant tool.It always seems like the participation of plugin > > > developers in answering questions from mere users like myself is > > > non-existent.Then lets not forget the poor documentation.The BB > book > > > was an excellent idea ,but sometimes it just does not address > problems > > > users face on the "setup battle field" and the "configuration > > > trenches" we're all familiar with.I'll give an example that relates > to > > > my experience.I posted questions relating to problems with the > Maven > > > Wagon plugin and in the process also thought it wise to see what > the > > > documents say.That led me to http://maven.apache.org/wagon/ and > > > clicking on the Getting Started link I ended up at the URL > > > http://maven.apache.org/wagon/guides/getting-started/index.html , > and > > > almost every link there leads to a : > > > = > &g
Re: Maven rant
I totally agree but I think that the problem is very difficult to solve, especially with all the incredible amount of undeocumented features that Maven has. Moreover, the problem is amplified by the fact that Maven allows the generation of most of the documentation: but if you don't write it, it won't write itself, so you will endup with dead links everywhere. As I see it, the problem in most Open Source projects is that developers do that on their free time, and developers aren't writers: those are two completely different tasks and the second one is not the most enjoyable. And last but not least: Open Source software is highly evolutive: why bother write some documentation for a feature that can be replaced by something more interesting in no-time and without any possible anticipation. The thing is that Maven is not the first Maven project I work with which faces that very issue. I had exactly the same problems a few months ago with Cocoon guys, and my remark is still the same: why do project leaders keep on considering documentation as a static thing. Think of Hibernate or PHP documentation: one base reference book with DYNAMIC comments in which people can share their thoughts and experiences about each feature/chapter, remarks that can be later integrated when the reference is rewritten. The problem is that, whereas development itself is a highly-collaborative and efficient process, nothing is really done so that documentation writing is collaborative enough: no workflow, no direct input, no dynamic comments, etc. Think of it: "Better Builds With Maven" is the most comprehensive documentation about Maven2. But was it written collaboratively? No. And I'm convinced that if it had been, it would be much higher quality and much more accessible today. Just my 2 cents. 2006/10/31, dhoffer <[EMAIL PROTECTED]>: Jeff, I use maven and I really like it and I don't want this to sound like negative criticism but you are right, the learning curve for maven newbie's is huge and there just isn't much good docs available. I have wound up getting bits of pieces of info from here and there...it just takes so long. It would be great if some maven gurus could solve this problem and make maven more accessible. Jeff Mutonho wrote: > > Is maven in the process of unintentionally killing itself due to poor > support and documentation?I may be wrong but I strongly feel that the > poor support and documentation is hampering adoption of an otherwise > brilliant tool.It always seems like the participation of plugin > developers in answering questions from mere users like myself is > non-existent.Then lets not forget the poor documentation.The BB book > was an excellent idea ,but sometimes it just does not address problems > users face on the "setup battle field" and the "configuration > trenches" we're all familiar with.I'll give an example that relates to > my experience.I posted questions relating to problems with the Maven > Wagon plugin and in the process also thought it wise to see what the > documents say.That led me to http://maven.apache.org/wagon/ and > clicking on the Getting Started link I ended up at the URL > http://maven.apache.org/wagon/guides/getting-started/index.html , and > almost every link there leads to a : > = > Page Not Found > Sorry, the page you requested was not found. This may because: > > * The page has moved, was outdated, or has not been created yet > * You typed the address incorrectly > * You following a link from another site that pointed to this page. > > We have recently reorganised our site, so please try looking in the > navigation on the left for the item you are looking for on Maven 1.x > or the Maven project. For information about Maven 2.0 or Continuum, > please visit their sub sites, available from the links in the top > right of the page. There is no need to report this broken link to the > Maven team, as errors are periodically monitored and repaired. > > === > > Same thing happens with the "Examples" link.Surely this cannot be a > pleasant user experience for anyone , let alone for a poor newbie who > might think looking at the docs is a good start.In my example, what > then can a user do besides thinking of putting one's neck on the > guillotine?One gets no help on the mailing list and the documentation > isn't helpful either. > I understand very well the idea that people are busy etc , but also > feel that there's need for more participation from plugin authors in > helping mere users like myself and others who get stuck with problems > only the maven gurus can solve...unless of course the plugins are only > to be used by the authors themselves. > Please don't take take this as whining , but rather , as a personal > view and perhaps constructive criticism. > > -- > > > Jeff Mutonho > > GoogleTalk : ejbengine > Skype: ejbengine > R
Re: Maven rant
Jeff, I use maven and I really like it and I don't want this to sound like negative criticism but you are right, the learning curve for maven newbie’s is huge and there just isn't much good docs available. I have wound up getting bits of pieces of info from here and there...it just takes so long. It would be great if some maven gurus could solve this problem and make maven more accessible. Jeff Mutonho wrote: > > Is maven in the process of unintentionally killing itself due to poor > support and documentation?I may be wrong but I strongly feel that the > poor support and documentation is hampering adoption of an otherwise > brilliant tool.It always seems like the participation of plugin > developers in answering questions from mere users like myself is > non-existent.Then lets not forget the poor documentation.The BB book > was an excellent idea ,but sometimes it just does not address problems > users face on the "setup battle field" and the "configuration > trenches" we're all familiar with.I'll give an example that relates to > my experience.I posted questions relating to problems with the Maven > Wagon plugin and in the process also thought it wise to see what the > documents say.That led me to http://maven.apache.org/wagon/ and > clicking on the Getting Started link I ended up at the URL > http://maven.apache.org/wagon/guides/getting-started/index.html , and > almost every link there leads to a : > = > Page Not Found > Sorry, the page you requested was not found. This may because: > > * The page has moved, was outdated, or has not been created yet > * You typed the address incorrectly > * You following a link from another site that pointed to this page. > > We have recently reorganised our site, so please try looking in the > navigation on the left for the item you are looking for on Maven 1.x > or the Maven project. For information about Maven 2.0 or Continuum, > please visit their sub sites, available from the links in the top > right of the page. There is no need to report this broken link to the > Maven team, as errors are periodically monitored and repaired. > > === > > Same thing happens with the "Examples" link.Surely this cannot be a > pleasant user experience for anyone , let alone for a poor newbie who > might think looking at the docs is a good start.In my example, what > then can a user do besides thinking of putting one's neck on the > guillotine?One gets no help on the mailing list and the documentation > isn't helpful either. > I understand very well the idea that people are busy etc , but also > feel that there's need for more participation from plugin authors in > helping mere users like myself and others who get stuck with problems > only the maven gurus can solve...unless of course the plugins are only > to be used by the authors themselves. > Please don't take take this as whining , but rather , as a personal > view and perhaps constructive criticism. > > -- > > > Jeff Mutonho > > GoogleTalk : ejbengine > Skype: ejbengine > Registered Linux user number 366042 > > - > 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#a7093319 Sent from the Maven - Users mailing list archive at Nabble.com. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Maven rant
Hello Jeff, I think it's really a trouble. But all will be OK, I'm sure of that. Best Regards. a cup of Java, cheers! Sha Jiang Jeff Mutonho wrote: > > Is maven in the process of unintentionally killing itself due to poor > support and documentation?I may be wrong but I strongly feel that the > poor support and documentation is hampering adoption of an otherwise > brilliant tool.It always seems like the participation of plugin > developers in answering questions from mere users like myself is > non-existent.Then lets not forget the poor documentation.The BB book > was an excellent idea ,but sometimes it just does not address problems > users face on the "setup battle field" and the "configuration > trenches" we're all familiar with.I'll give an example that relates to > my experience.I posted questions relating to problems with the Maven > Wagon plugin and in the process also thought it wise to see what the > documents say.That led me to http://maven.apache.org/wagon/ and > clicking on the Getting Started link I ended up at the URL > http://maven.apache.org/wagon/guides/getting-started/index.html , and > almost every link there leads to a : > = > Page Not Found > Sorry, the page you requested was not found. This may because: > > * The page has moved, was outdated, or has not been created yet > * You typed the address incorrectly > * You following a link from another site that pointed to this page. > > We have recently reorganised our site, so please try looking in the > navigation on the left for the item you are looking for on Maven 1.x > or the Maven project. For information about Maven 2.0 or Continuum, > please visit their sub sites, available from the links in the top > right of the page. There is no need to report this broken link to the > Maven team, as errors are periodically monitored and repaired. > > === > > Same thing happens with the "Examples" link.Surely this cannot be a > pleasant user experience for anyone , let alone for a poor newbie who > might think looking at the docs is a good start.In my example, what > then can a user do besides thinking of putting one's neck on the > guillotine?One gets no help on the mailing list and the documentation > isn't helpful either. > I understand very well the idea that people are busy etc , but also > feel that there's need for more participation from plugin authors in > helping mere users like myself and others who get stuck with problems > only the maven gurus can solve...unless of course the plugins are only > to be used by the authors themselves. > Please don't take take this as whining , but rather , as a personal > view and perhaps constructive criticism. > > -- > > > Jeff Mutonho > > GoogleTalk : ejbengine > Skype: ejbengine > Registered Linux user number 366042 > > - > 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#a7091094 Sent from the Maven - Users mailing list archive at Nabble.com. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
