Re: Making the current web site suck less
Tim, did anything ever come of this? - Brett Tim O'Brien wrote: Brett, Sure will do, I think a JIRA task wouldn't do this justice. I'm working on a mockup in Adobe Illustrator ;-) On 3/9/06, Brett Porter [EMAIL PROTECTED] wrote: Tim, There's plenty of points here and on your blog. Can you please put this in a proposal form for how to make specific improvements. ie, for everything that you think is wrong, say how you'd make it right, in point form so each can be specifically addressed and turned into jira tasks. - Brett Tim O'Brien wrote: I'm not saying this to be contrary, bear with me: most people that use Maven don't care to know much about the internals or how it is being developed. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] -- Brett Porter [EMAIL PROTECTED] Apache Maven - http://maven.apache.org/ Better Builds with Maven - http://library.mergere.com/ - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Making the current web site suck less
It aims to be a page or a couple of pages. I don't have clear idea on it. yesterday i wrote it in two pages : a main page with sample doco and an advanced page with an exhautive doco (not in my sample be should be) But i think it is not a navigation. Raphaël 2006/3/10, Brett Porter [EMAIL PROTECTED]: Thanks for attempting this. IS this intended to be a navigation, a page, a series of pages? I'm a little confused. Do you have any feedback on my original proposal on this thread? It tried to examine many of the same problems. - Brett Raphaël Piéroni wrote: Hi, So here is a cleaner proposition for the site. This proposition is focused on the documentation for the user. I assume the user is a java developer but may not be a maven developer. What do a developer (and maven user) want to know: - where to find the software, - how to install it, - how to configure maven use in a proper environment, - how to configure it's project, - how to run maven and get it project properly packaged. Therefore i propose the following presentation of the maven site. Reading Convention: _a_ is a link to a, (text) is a comment, text is a variable Main page : Title missing _what is maven ?_ _download_ _installation_ _getting started_ Maven Concepts _introduction_ _project descriptor_ _artifact_ _life cycle_ _repositories_ _plugins_ _directory convention_ _archetypes_ Normative References _Project Object Model_ _User Settings_ Basic Documentation (in the project life cycle order and in multi column) Archetypes Guides _using a project archetype_ _creating an archetype_ Plugins _archetype plugin_ Archetypes _quickstart_ _webapp_ Generating Sources Guides _no idea_ Plugins _xdoclet_ _antlr_ _modello_ Testing Guides _unit testing_ _integration testing_ _plugin testing_ (move to advanced documentation ?) Plugins _surefire_ _cargo_ Deployment Guides _creating an enterprise repository_ Plugins _deploy_ _tomcat_ Site Guides _creating a maven site_ _using reports_ Plugins _site_ _changes_ Reports _cobertura_ _javadoc_ _changelog_ _checkstyle_ Advanced Documentation (in the project life cycle order and in multi column) Maven in an Ide Guides _using maven in IDEA_ Plugins _eclipse_ Ide extensions _mevenide2_ Plugin Development Documentation Guides _creating a Plugin in Java_ _creating a Plugin using Ant_ Plugins _plugin_ Reports _mojo description_ Packagings Guides _creating webapps_ _creating desktop applications_ Plugins _war_ _ejb_ Associated Artifacts Guides _deploying the sources along with the main artifact_ _using an assembly_ Plugins _source_ _assembly_ Misc. Guide _filtering resources_ End of page For a better use of the development process, do this proposition must belong to a wiki page or in the mailing list it is correct ? Regards, Raphaël - 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: Making the current web site suck less
Cool. I think this is a good idea. In my original proposal: * The documentation is a big list of links. I think we should categorise them by topic instead of type, or perhaps as Jesse suggests we should have a cross reference/index - so we could have a page that lists all the howtos and guides, then another that lists the docs related to artifacts, plugins, etc. These seem like good starts at the type of alternate indices I was thinking of. Would you mind capturing these in a JIRA item? - Brett Piéroni Raphaël wrote: It aims to be a page or a couple of pages. I don't have clear idea on it. yesterday i wrote it in two pages : a main page with sample doco and an advanced page with an exhautive doco (not in my sample be should be) But i think it is not a navigation. Raphaël 2006/3/10, Brett Porter [EMAIL PROTECTED]: Thanks for attempting this. IS this intended to be a navigation, a page, a series of pages? I'm a little confused. Do you have any feedback on my original proposal on this thread? It tried to examine many of the same problems. - Brett Raphaël Piéroni wrote: Hi, So here is a cleaner proposition for the site. This proposition is focused on the documentation for the user. I assume the user is a java developer but may not be a maven developer. What do a developer (and maven user) want to know: - where to find the software, - how to install it, - how to configure maven use in a proper environment, - how to configure it's project, - how to run maven and get it project properly packaged. Therefore i propose the following presentation of the maven site. Reading Convention: _a_ is a link to a, (text) is a comment, text is a variable Main page : Title missing _what is maven ?_ _download_ _installation_ _getting started_ Maven Concepts _introduction_ _project descriptor_ _artifact_ _life cycle_ _repositories_ _plugins_ _directory convention_ _archetypes_ Normative References _Project Object Model_ _User Settings_ Basic Documentation (in the project life cycle order and in multi column) Archetypes Guides _using a project archetype_ _creating an archetype_ Plugins _archetype plugin_ Archetypes _quickstart_ _webapp_ Generating Sources Guides _no idea_ Plugins _xdoclet_ _antlr_ _modello_ Testing Guides _unit testing_ _integration testing_ _plugin testing_ (move to advanced documentation ?) Plugins _surefire_ _cargo_ Deployment Guides _creating an enterprise repository_ Plugins _deploy_ _tomcat_ Site Guides _creating a maven site_ _using reports_ Plugins _site_ _changes_ Reports _cobertura_ _javadoc_ _changelog_ _checkstyle_ Advanced Documentation (in the project life cycle order and in multi column) Maven in an Ide Guides _using maven in IDEA_ Plugins _eclipse_ Ide extensions _mevenide2_ Plugin Development Documentation Guides _creating a Plugin in Java_ _creating a Plugin using Ant_ Plugins _plugin_ Reports _mojo description_ Packagings Guides _creating webapps_ _creating desktop applications_ Plugins _war_ _ejb_ Associated Artifacts Guides _deploying the sources along with the main artifact_ _using an assembly_ Plugins _source_ _assembly_ Misc. Guide _filtering resources_ End of page For a better use of the development process, do this proposition must belong to a wiki page or in the mailing list it is correct ? Regards, Raphaël - 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] - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Making the current web site suck less
I'm sorry, I don't know what to say to the jira issue As you know i'm a bit new to open source processes. I never released the freeform plugin because i don't know how. Regards, Raphaël 2006/3/10, Brett Porter [EMAIL PROTECTED]: Cool. I think this is a good idea. In my original proposal: * The documentation is a big list of links. I think we should categorise them by topic instead of type, or perhaps as Jesse suggests we should have a cross reference/index - so we could have a page that lists all the howtos and guides, then another that lists the docs related to artifacts, plugins, etc. These seem like good starts at the type of alternate indices I was thinking of. Would you mind capturing these in a JIRA item? - Brett Piéroni Raphaël wrote: It aims to be a page or a couple of pages. I don't have clear idea on it. yesterday i wrote it in two pages : a main page with sample doco and an advanced page with an exhautive doco (not in my sample be should be) But i think it is not a navigation. Raphaël 2006/3/10, Brett Porter [EMAIL PROTECTED]: Thanks for attempting this. IS this intended to be a navigation, a page, a series of pages? I'm a little confused. Do you have any feedback on my original proposal on this thread? It tried to examine many of the same problems. - Brett Raphaël Piéroni wrote: Hi, So here is a cleaner proposition for the site. This proposition is focused on the documentation for the user. I assume the user is a java developer but may not be a maven developer. What do a developer (and maven user) want to know: - where to find the software, - how to install it, - how to configure maven use in a proper environment, - how to configure it's project, - how to run maven and get it project properly packaged. Therefore i propose the following presentation of the maven site. Reading Convention: _a_ is a link to a, (text) is a comment, text is a variable Main page : Title missing _what is maven ?_ _download_ _installation_ _getting started_ Maven Concepts _introduction_ _project descriptor_ _artifact_ _life cycle_ _repositories_ _plugins_ _directory convention_ _archetypes_ Normative References _Project Object Model_ _User Settings_ Basic Documentation (in the project life cycle order and in multi column) Archetypes Guides _using a project archetype_ _creating an archetype_ Plugins _archetype plugin_ Archetypes _quickstart_ _webapp_ Generating Sources Guides _no idea_ Plugins _xdoclet_ _antlr_ _modello_ Testing Guides _unit testing_ _integration testing_ _plugin testing_ (move to advanced documentation ?) Plugins _surefire_ _cargo_ Deployment Guides _creating an enterprise repository_ Plugins _deploy_ _tomcat_ Site Guides _creating a maven site_ _using reports_ Plugins _site_ _changes_ Reports _cobertura_ _javadoc_ _changelog_ _checkstyle_ Advanced Documentation (in the project life cycle order and in multi column) Maven in an Ide Guides _using maven in IDEA_ Plugins _eclipse_ Ide extensions _mevenide2_ Plugin Development Documentation Guides _creating a Plugin in Java_ _creating a Plugin using Ant_ Plugins _plugin_ Reports _mojo description_ Packagings Guides _creating webapps_ _creating desktop applications_ Plugins _war_ _ejb_ Associated Artifacts Guides _deploying the sources along with the main artifact_ _using an assembly_ Plugins _source_ _assembly_ Misc. Guide _filtering resources_ End of page For a better use of the development process, do this proposition must belong to a wiki page or in the mailing list it is correct ? Regards, Raphaël - 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] - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Making the current web site suck less
On 3/9/06, Brett Porter [EMAIL PROTECTED] wrote: Tim O'Brien wrote: I read your response, clicked on the Geronimo site, and wanted to believe that that was possible with Maven. But, if you look at https://svn.apache.org/repos/asf/geronimo/site/ It's either Maven 1.x or Ant the directory contains a v3 POM, but it also contains an . The NOTES.txt begins Download Ant from http://ant.apache.org;. It's not, but it's entirely possible with the current SVN version of the site plugin and is where I want it to go. It's just a replacement velocity template. I didn't understand your point about the structure of the XHTML in your blog. It should be reasonably flexible for CSS based layout, and in the event you need something different you can fall back to the packaged up velocity template. - Brett What I mean by this. Point a graphics desiger at a Maven site - make this site look great with CSS. I think you'll find that the graphic designer is going to request so many changes to structure it would almost be easier for an organization to just fork and customize the site plugin rather than deal with what is produced.I would agree that Maven provides a reasonable amount of flexibility, but I guess I have yet to see a Maven site that doesn't look like a Maven site. Maybe we need a site that customizes the CSS to show people what is possible. A Zen Garden for Maven. Tim - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Making the current web site suck less
Brett, Sure will do, I think a JIRA task wouldn't do this justice. I'm working on a mockup in Adobe Illustrator ;-) On 3/9/06, Brett Porter [EMAIL PROTECTED] wrote: Tim, There's plenty of points here and on your blog. Can you please put this in a proposal form for how to make specific improvements. ie, for everything that you think is wrong, say how you'd make it right, in point form so each can be specifically addressed and turned into jira tasks. - Brett Tim O'Brien wrote: I'm not saying this to be contrary, bear with me: most people that use Maven don't care to know much about the internals or how it is being developed. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Making the current web site suck less
Done http://jira.codehaus.org/browse/MNG-2143 Raphaël Brett Porter a écrit : Cool. I think this is a good idea. In my original proposal: * The documentation is a big list of links. I think we should categorise them by topic instead of type, or perhaps as Jesse suggests we should have a cross reference/index - so we could have a page that lists all the howtos and guides, then another that lists the docs related to artifacts, plugins, etc. These seem like good starts at the type of alternate indices I was thinking of. Would you mind capturing these in a JIRA item? - Brett - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Making the current web site suck less
Hi, what about this kind of cutting : Reports - guides - plugins (jxr, javancss, ...) Archetypes - guides - plugins (quickstart,...) Generators - guides - plugins (modello, torque, ...) IDE - guides - plugins Associated artifacts
Re: Making the current web site suck less
missing : Languages -guides - plugins (c#, aspectj) Deployment - guides - plugins (jboss, tomcat) Test - guides - plugins (surefire, cargo) Continuous integration - guides Packaging - guides - plugins and also some doco that do not fit into the guide/plugins separation like getting started, references of pom and settings,... Regards Raphaël 2006/3/9, Piéroni Raphaël [EMAIL PROTECTED]: Hi, what about this kind of cutting : Reports - guides - plugins (jxr, javancss, ...) Archetypes - guides - plugins (quickstart,...) Generators - guides - plugins (modello, torque, ...) IDE - guides - plugins Associated artifacts
Re: Making the current web site suck less
Hi, So here is a cleaner proposition for the site. This proposition is focused on the documentation for the user. I assume the user is a java developer but may not be a maven developer. What do a developer (and maven user) want to know: - where to find the software, - how to install it, - how to configure maven use in a proper environment, - how to configure it's project, - how to run maven and get it project properly packaged. Therefore i propose the following presentation of the maven site. Reading Convention: _a_ is a link to a, (text) is a comment, text is a variable Main page : Title missing _what is maven ?_ _download_ _installation_ _getting started_ Maven Concepts _introduction_ _project descriptor_ _artifact_ _life cycle_ _repositories_ _plugins_ _directory convention_ _archetypes_ Normative References _Project Object Model_ _User Settings_ Basic Documentation (in the project life cycle order and in multi column) Archetypes Guides _using a project archetype_ _creating an archetype_ Plugins _archetype plugin_ Archetypes _quickstart_ _webapp_ Generating Sources Guides _no idea_ Plugins _xdoclet_ _antlr_ _modello_ Testing Guides _unit testing_ _integration testing_ _plugin testing_ (move to advanced documentation ?) Plugins _surefire_ _cargo_ Deployment Guides _creating an enterprise repository_ Plugins _deploy_ _tomcat_ Site Guides _creating a maven site_ _using reports_ Plugins _site_ _changes_ Reports _cobertura_ _javadoc_ _changelog_ _checkstyle_ Advanced Documentation (in the project life cycle order and in multi column) Maven in an Ide Guides _using maven in IDEA_ Plugins _eclipse_ Ide extensions _mevenide2_ Plugin Development Documentation Guides _creating a Plugin in Java_ _creating a Plugin using Ant_ Plugins _plugin_ Reports _mojo description_ Packagings Guides _creating webapps_ _creating desktop applications_ Plugins _war_ _ejb_ Associated Artifacts Guides _deploying the sources along with the main artifact_ _using an assembly_ Plugins _source_ _assembly_ Misc. Guide _filtering resources_ End of page For a better use of the development process, do this proposition must belong to a wiki page or in the mailing list it is correct ? Regards, Raphaël - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Making the current web site suck less
Tim O'Brien wrote: On 3/8/06, John Casey [EMAIL PROTECTED] wrote: snip Something to think about is maybe not having the initial Maven page be a Maven site. ASF sites in general seems to be more Developer focused than user focused. What if the initial Maven site were more like the front pages of Mozilla or Rails. An attractive logo, links to resources and materials, an introduction. The home page should be user focused, Maven developers are a minority of the audience here. Are you saying that the developer-centric tendency is appropriate for ASF project web sites, then? I'd tend to say that for a product like Maven (not an API, like commons-cli, for instance) it's worth striving to help the user. Since Maven is an Apache product/project, I'd say that having a developer site on a different physical location would be bad...they're different aspects of the same product/project. That said, I think we need to section the developer docs off and put them a click or so in from the main landing page...probably with their own landing page. I think I agree with you. When I said developer-centric I meant apache-developer-centric. IMO, more projects need to think about the user who has 30 seconds to figure out the best way to download/use Derby. The current Maven site has too many links, too much distracting people from what should be a simple message - Download Maven, you won't believe how you developed without it. We promise..I'm not saying that we should all become marketing people, but it's something to consider. I agree with you on that point. My point was that physical separation of the websites might not be appropriate or necessary, since IMO every ASF project that releases a product (not an API) should apply this advice, and therefore should have a user-driven aspect, behind which lurks a developer-driven section, one click away. The developer pages don't have to invade the landing page, but there should be a link (to elsewhere on the same physical web site). It's not a simple hierarchy, but then, we have a great deal of variation among our audience members. As these audience members [possibly] transition from users to contributors and so on, we don't want a separation like this to get in their way...there should be *some* cohesiveness, I would think... I'm not saying this to be contrary, bear with me: most people that use Maven don't care to know much about the internals or how it is being developed. They simply want to download a product that works, is well documented, and use it. A small minority of those users will get an itch that needs to be scratched or decide that the gift of free software should be repaid by involvement in a community. So, if you wrote up a survey, and quizzed people who use Maven every day, I think you'd probably find that most of them think Jason van Zyl is a famous magician and the Meritocracy is a spell in Dungeons and Dragons. I'm not saying this as a cynical jibe, but to make the point that regardless of the Maven website, we will always about an equal mix - out of 100 - 95 people download Maven, 5 subscribe to the users list for a week, maybe 4 ask questions on the user list, and, if you are lucky, 1 submits a patch. And even that's overestimating, apply that forumla to the httpd project and it would have 10^5 patches submitted per year. Turn your statement around. audience members [possibly] transition form users to contributors. Assume that a simpler user focused launch page made it easier for people to adopt Maven. If this separation of user-focused and developer-focused documentation increases the population of users, we've increase the pool of potential contributors. I'm betting on the fact that as users root around the documentation, they'll catch on to the fact that this is the ASF they will pick up the community. I think a good strategy is to make the landing page for Maven as simple as possible, with a good short sell, as little text as possible, link to download, and some news and announcements. The Maven launch page should be very similar to the Mozilla launch page - there are still links to the developer pages. See my comments above. Again, this isn't about merging the developer and user communities, forcing them to read the same webpages and filter the content that pertains to them. It's about whether we want to move toward uniting all of the Maven project content to make it look like part of the same site, albeit in different sections. I can't think of very many people who might disagree that our site needs some organizational help, and a heavy-ish touch of user-friendliness. Instead we've got a link named Netbeans Module, a link on the top of the page to Maven followed by a link to Maven 2.x and Maven 1.x. All the links have a 20% change of having a completely different skin. There are links to a Wiki and external sites that are not labeled as such. There is a Project Team
Re: Making the current web site suck less
On 3/9/06, John Casey [EMAIL PROTECTED] wrote: snip/ I agree with you on that point. My point was that physical separation of the websites might not be appropriate or necessary, since IMO every ASF project that releases a product (not an API) should apply this advice, and therefore should have a user-driven aspect, behind which lurks a developer-driven section, one click away. The developer pages don't have to invade the landing page, but there should be a link (to elsewhere on the same physical web site). Sure. maybe the same physical web site maybe a different one. The Developer and User sites might share a color scheme and a logo, but they should be able to have completely different structure. completely different layout, different context, etc.I'm convinced Maven needs a focused documentation project. I'm not convinced that it makes sense to house that project within the foundation. That's what drives my suggestion about a Maven user site being totally separate from a developer site. Here's where I think we miss. In the absence of a Maven plugin that creates a site that a designer can really control, can really customize. That has DIV structure and CSS that a designer can be happy with, we probably won't enable people to get to the point where they can apply a good design to a Maven site. It's not a simple hierarchy, but then, we have a great deal of variation among our audience members. As these audience members [possibly] transition from users to contributors and so on, we don't want a separation like this to get in their way...there should be *some* cohesiveness, I would think... See my comments above. Again, this isn't about merging the developer and user communities, forcing them to read the same webpages and filter the content that pertains to them. It's about whether we want to move toward uniting all of the Maven project content to make it look like part of the same site, albeit in different sections. I can't think of very many people who might disagree that our site needs some organizational help, and a heavy-ish touch of user-friendliness. And again, I think that the Maven site should be a lot more like a community site that aggregates blogs, lists articles, news items. In the absence of a runtime container uses some Javscript to display RSS feeds of the last 10 user posts. Look around at Sourceforge sometime, and see how many of the non-Maven sites out there are well-designed. The medocrity of the average shouldn't be the argument here. If Maven intends to revolutionize the way people approach software projects. It should strive to solve this problem as elegantly as it solves dependency management.
Re: Making the current web site suck less
Please review: http://mail-archives.apache.org/mod_mbox/maven-dev/200602.mbox/[EMAIL PROTECTED] And provide feedback. Closely related to: http://mail-archives.apache.org/mod_mbox/maven-dev/200602.mbox/[EMAIL PROTECTED] These have been kicking around since early January and I haven't received feedback yet, but they are proposals that should address exactly this. - Brett Tim O'Brien wrote: Having to choose between publishing the latest and greatest docs and only the released version is a problem that Maven seems to have created for itself. Same issue comes up in other projects frequently - Commons has a problem because some of the sites only publish on a release. Latest and greatest are almost never there. What about publishing the latest and greatest docs to another directory? The Maven site gets pushed to a directory that has a version of a label. http://maven.apache.org/version/1.0 , http://maven.apache.org/version/2.0.2, and http://maven.apache.org/version/trunk. This way the Maven site can have a nightly publish of the most current Maven site to Trunk every single day, but still keep legacy docs around intact for people using older versions of the product. The consumer site can point to the latest release, and the developer site can point to trunk. The Maven site plugin would need some mechanism for adding a skin to a site to clearly identify it as Development. On 3/7/06, Wendy Smoak [EMAIL PROTECTED] wrote: On 3/7/06, Brett Porter [EMAIL PROTECTED] wrote: * I'm still a little torn on where plugin docs go. No hurry on this, but something to ponder. We definitely need to make the references for those integrate better. Site/skin inheritance will help No matter where they go, I think they need to be updated more often. Random example... the assembly plugin docs are wrong, and have been that way for months. (it's descriptorId, not maven.assembly.descriptorId.) * http://maven.apache.org/plugins/maven-assembly-plugin/howto.html I would like to see the latest and greatest docs on the main site. Yes, they'll be ahead of the released version, but not by much, and (hopefully) not for long.When the answer to a lot of X doesn't work questions is It's fixed in the trunk, use a snapshot, it would be nice to have the snapshot docs available in a centralized place. This also makes it more fun to contribute to the documentation, because you get to see your work in print right away. Thanks for updating the main site. :) -- 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: Making the current web site suck less
Tim O'Brien wrote: Something to think about is maybe not having the initial Maven page be a Maven site. ASF sites in general seems to be more Developer focused than user focused. What if the initial Maven site were more like the front pages of Mozilla or Rails. An attractive logo, links to resources and materials, an introduction. The home page should be user focused, Maven developers are a minority of the audience here. I had a proposal for the initial page in the very first mail in the thread and got no feedback. Any chance you could comment on that since it has specifics? Here it is again: http://mail-archives.apache.org/mod_mbox/maven-dev/200603.mbox/[EMAIL PROTECTED] - Brett - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Making the current web site suck less
Tim, There's plenty of points here and on your blog. Can you please put this in a proposal form for how to make specific improvements. ie, for everything that you think is wrong, say how you'd make it right, in point form so each can be specifically addressed and turned into jira tasks. - Brett Tim O'Brien wrote: I'm not saying this to be contrary, bear with me: most people that use Maven don't care to know much about the internals or how it is being developed. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Making the current web site suck less
Brian K. Wallace wrote: Then there's the content debate... Getting Started with Maven goes on _forever_. To get started?!? And that's entirely outside the scope of the documentation link (which doesn't quite go on forever - just links forever). And the first link on documentation? Getting Started. [and NO, I'm not saying there's too much documentation now ;-)] I couldn't agree more. My original getting started guide was much shorter. I think it needs to be chopped up. It needs to be a 10 minute test (which I timed myself on the original one and I could read and step through in 5 minutes, so I figured those that hadn't encountered it before had a good chance of doing it in 10). Let's get this request into JIRA. - Brett = - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Making the current web site suck less
Tim O'Brien wrote: I read your response, clicked on the Geronimo site, and wanted to believe that that was possible with Maven. But, if you look at https://svn.apache.org/repos/asf/geronimo/site/ It's either Maven 1.x or Ant the directory contains a v3 POM, but it also contains an . The NOTES.txt begins Download Ant from http://ant.apache.org;. It's not, but it's entirely possible with the current SVN version of the site plugin and is where I want it to go. It's just a replacement velocity template. I didn't understand your point about the structure of the XHTML in your blog. It should be reasonably flexible for CSS based layout, and in the event you need something different you can fall back to the packaged up velocity template. - Brett - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Making the current web site suck less
Tim O'Brien wrote: And again, I think that the Maven site should be a lot more like a community site that aggregates blogs, lists articles, news items. In the absence of a runtime container uses some Javscript to display RSS feeds of the last 10 user posts. I don't know about making the primary site just this, but I think it would be a great addition. We made a small step with mavenblogs.com but never really got it properly integrated. I recently suggested we grab the planet software and put up a separate site for this as a start. It's always just been a matter of available time. - Brett - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Making the current web site suck less
Thanks for attempting this. IS this intended to be a navigation, a page, a series of pages? I'm a little confused. Do you have any feedback on my original proposal on this thread? It tried to examine many of the same problems. - Brett Raphaël Piéroni wrote: Hi, So here is a cleaner proposition for the site. This proposition is focused on the documentation for the user. I assume the user is a java developer but may not be a maven developer. What do a developer (and maven user) want to know: - where to find the software, - how to install it, - how to configure maven use in a proper environment, - how to configure it's project, - how to run maven and get it project properly packaged. Therefore i propose the following presentation of the maven site. Reading Convention: _a_ is a link to a, (text) is a comment, text is a variable Main page : Title missing _what is maven ?_ _download_ _installation_ _getting started_ Maven Concepts _introduction_ _project descriptor_ _artifact_ _life cycle_ _repositories_ _plugins_ _directory convention_ _archetypes_ Normative References _Project Object Model_ _User Settings_ Basic Documentation (in the project life cycle order and in multi column) Archetypes Guides _using a project archetype_ _creating an archetype_ Plugins _archetype plugin_ Archetypes _quickstart_ _webapp_ Generating Sources Guides _no idea_ Plugins _xdoclet_ _antlr_ _modello_ Testing Guides _unit testing_ _integration testing_ _plugin testing_ (move to advanced documentation ?) Plugins _surefire_ _cargo_ Deployment Guides _creating an enterprise repository_ Plugins _deploy_ _tomcat_ Site Guides _creating a maven site_ _using reports_ Plugins _site_ _changes_ Reports _cobertura_ _javadoc_ _changelog_ _checkstyle_ Advanced Documentation (in the project life cycle order and in multi column) Maven in an Ide Guides _using maven in IDEA_ Plugins _eclipse_ Ide extensions _mevenide2_ Plugin Development Documentation Guides _creating a Plugin in Java_ _creating a Plugin using Ant_ Plugins _plugin_ Reports _mojo description_ Packagings Guides _creating webapps_ _creating desktop applications_ Plugins _war_ _ejb_ Associated Artifacts Guides _deploying the sources along with the main artifact_ _using an assembly_ Plugins _source_ _assembly_ Misc. Guide _filtering resources_ End of page For a better use of the development process, do this proposition must belong to a wiki page or in the mailing list it is correct ? Regards, Raphaël - 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: Making the current web site suck less
that becomes an epic adventure, close to none of the methods/classes have a usable javadoc (most have none). the same applies to plugin parameters, I always go to the plugin doc first, but then realize it's useless and try finding stuff in the other site documentation. Also please consider removing the Discovered parameters that just don't add value but confuse (unless I missed the point entirely) +1 on that. Milos On 3/8/06, Rinku [EMAIL PROTECTED] wrote: Since we talk about 'latest and greatest', I wonder why javadocs published online cannot serve as 'latest and greatest' docs? I am +1 to Carlos' idea about documenting almost all methods. If we were to publish API docs for Maven and Plugins on the website (some separate URL) with every Maven release build or every nightly build, at least they would always reflect the 'latest and greatest' for the code. Cheers, Rahul Brian K. Wallace wrote: -BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Wendy Smoak wrote: On 3/7/06, Brett Porter [EMAIL PROTECTED] wrote: * I'm still a little torn on where plugin docs go. No hurry on this, but something to ponder. We definitely need to make the references for those integrate better. Site/skin inheritance will help No matter where they go, I think they need to be updated more often. Random example... the assembly plugin docs are wrong, and have been that way for months. (it's descriptorId, not maven.assembly.descriptorId.) * http://maven.apache.org/plugins/maven-assembly-plugin/howto.html I would like to see the latest and greatest docs on the main site. Yes, they'll be ahead of the released version, but not by much, and (hopefully) not for long.When the answer to a lot of X doesn't work questions is It's fixed in the trunk, use a snapshot, it would be nice to have the snapshot docs available in a centralized place. This also makes it more fun to contribute to the documentation, because you get to see your work in print right away. Thanks for updating the main site. :) -- Wendy While I agree that it would be nice to have the 'latest and greatest' docs on the main site, I don't believe having them as the only documentation is a good idea at all. The documentation should be able to evolve after a release to make them better, but having documentation online that applies to trunk code and not released code tends to equate bad documentation (the docs say I can do X. oh, that's in the trunk, use a snapshot). If you aren't going to have two sets - one for released code and one for trunk code, only go with released code. If there are changes that can be made to make the released code's documentation better between releases, by all means - make it live as soon as practical. My .02 Brian -BEGIN PGP SIGNATURE- Version: GnuPG v1.2.5 (MingW32) iD8DBQFEDjrpaCoPKRow/gARAiGlAJ98kZI0ItEEusrpmgIAT/jaQBaLXgCfbUhi 8iPFWc+Loyp9VtbXHxd6eqY= =cs6U -END PGP SIGNATURE- - 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] - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
RE: Making the current web site suck less
It would be great if maven had the ability to specify a snapshot site url similar to how the repositories work. Then a snapshot rev gets its site deployed some where different than the release version. -Original Message- From: Brian K. Wallace [mailto:[EMAIL PROTECTED] Sent: Tuesday, March 07, 2006 9:01 PM To: Maven Developers List Subject: Re: Making the current web site suck less -BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Wendy Smoak wrote: On 3/7/06, Brett Porter [EMAIL PROTECTED] wrote: * I'm still a little torn on where plugin docs go. No hurry on this, but something to ponder. We definitely need to make the references for those integrate better. Site/skin inheritance will help No matter where they go, I think they need to be updated more often. Random example... the assembly plugin docs are wrong, and have been that way for months. (it's descriptorId, not maven.assembly.descriptorId.) * http://maven.apache.org/plugins/maven-assembly-plugin/howto.html I would like to see the latest and greatest docs on the main site. Yes, they'll be ahead of the released version, but not by much, and (hopefully) not for long.When the answer to a lot of X doesn't work questions is It's fixed in the trunk, use a snapshot, it would be nice to have the snapshot docs available in a centralized place. This also makes it more fun to contribute to the documentation, because you get to see your work in print right away. Thanks for updating the main site. :) -- Wendy While I agree that it would be nice to have the 'latest and greatest' docs on the main site, I don't believe having them as the only documentation is a good idea at all. The documentation should be able to evolve after a release to make them better, but having documentation online that applies to trunk code and not released code tends to equate bad documentation (the docs say I can do X. oh, that's in the trunk, use a snapshot). If you aren't going to have two sets - one for released code and one for trunk code, only go with released code. If there are changes that can be made to make the released code's documentation better between releases, by all means - make it live as soon as practical. My .02 Brian -BEGIN PGP SIGNATURE- Version: GnuPG v1.2.5 (MingW32) iD8DBQFEDjrpaCoPKRow/gARAiGlAJ98kZI0ItEEusrpmgIAT/jaQBaLXgCfbUhi 8iPFWc+Loyp9VtbXHxd6eqY= =cs6U -END PGP SIGNATURE- - 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: Making the current web site suck less
Having to choose between publishing the latest and greatest docs and only the released version is a problem that Maven seems to have created for itself. Same issue comes up in other projects frequently - Commons has a problem because some of the sites only publish on a release. Latest and greatest are almost never there. What about publishing the latest and greatest docs to another directory? The Maven site gets pushed to a directory that has a version of a label. http://maven.apache.org/version/1.0 , http://maven.apache.org/version/2.0.2, and http://maven.apache.org/version/trunk. This way the Maven site can have a nightly publish of the most current Maven site to Trunk every single day, but still keep legacy docs around intact for people using older versions of the product. The consumer site can point to the latest release, and the developer site can point to trunk. The Maven site plugin would need some mechanism for adding a skin to a site to clearly identify it as Development. On 3/7/06, Wendy Smoak [EMAIL PROTECTED] wrote: On 3/7/06, Brett Porter [EMAIL PROTECTED] wrote: * I'm still a little torn on where plugin docs go. No hurry on this, but something to ponder. We definitely need to make the references for those integrate better. Site/skin inheritance will help No matter where they go, I think they need to be updated more often. Random example... the assembly plugin docs are wrong, and have been that way for months. (it's descriptorId, not maven.assembly.descriptorId.) * http://maven.apache.org/plugins/maven-assembly-plugin/howto.html I would like to see the latest and greatest docs on the main site. Yes, they'll be ahead of the released version, but not by much, and (hopefully) not for long.When the answer to a lot of X doesn't work questions is It's fixed in the trunk, use a snapshot, it would be nice to have the snapshot docs available in a centralized place. This also makes it more fun to contribute to the documentation, because you get to see your work in print right away. Thanks for updating the main site. :) -- Wendy - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Making the current web site suck less
I think that's a good idea. In m1 we are already using the maven.site.stage.address property to publish sites more frequently to our personal pages (eg [1]) and I refer people to this site occasionally. This has the obvious drawback that the 'latest-and-greatest' docs for different plugins are always on different people's pages. I could imagine something like http://maven.apache.org/maven-1.x/stage-site/ where the whole m1 site is replicated but with more up-to date pages, and the main site only gets updated for releases or documentation bug fixes. -Lukas [1] http://people.apache.org/~ltheussl/maven-stage-site/maven-1.x/reference/plugins/ Tim O'Brien wrote: Having to choose between publishing the latest and greatest docs and only the released version is a problem that Maven seems to have created for itself. Same issue comes up in other projects frequently - Commons has a problem because some of the sites only publish on a release. Latest and greatest are almost never there. What about publishing the latest and greatest docs to another directory? The Maven site gets pushed to a directory that has a version of a label. http://maven.apache.org/version/1.0 , http://maven.apache.org/version/2.0.2, and http://maven.apache.org/version/trunk. This way the Maven site can have a nightly publish of the most current Maven site to Trunk every single day, but still keep legacy docs around intact for people using older versions of the product. The consumer site can point to the latest release, and the developer site can point to trunk. The Maven site plugin would need some mechanism for adding a skin to a site to clearly identify it as Development. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Making the current web site suck less
+1 Maybe we can put a banner at the top of each page that marks the version it refers to or something. If we styled the reference doco as a manual, it could be part of the page layout that ties it together. I'd be willing to trade a bit of the lookfeel for that sort of information, as it seems to me that it would reduce confusion. -john Tim O'Brien wrote: Having to choose between publishing the latest and greatest docs and only the released version is a problem that Maven seems to have created for itself. Same issue comes up in other projects frequently - Commons has a problem because some of the sites only publish on a release. Latest and greatest are almost never there. What about publishing the latest and greatest docs to another directory? The Maven site gets pushed to a directory that has a version of a label. http://maven.apache.org/version/1.0 , http://maven.apache.org/version/2.0.2, and http://maven.apache.org/version/trunk. This way the Maven site can have a nightly publish of the most current Maven site to Trunk every single day, but still keep legacy docs around intact for people using older versions of the product. The consumer site can point to the latest release, and the developer site can point to trunk. The Maven site plugin would need some mechanism for adding a skin to a site to clearly identify it as Development. On 3/7/06, Wendy Smoak [EMAIL PROTECTED] wrote: On 3/7/06, Brett Porter [EMAIL PROTECTED] wrote: * I'm still a little torn on where plugin docs go. No hurry on this, but something to ponder. We definitely need to make the references for those integrate better. Site/skin inheritance will help No matter where they go, I think they need to be updated more often. Random example... the assembly plugin docs are wrong, and have been that way for months. (it's descriptorId, not maven.assembly.descriptorId.) * http://maven.apache.org/plugins/maven-assembly-plugin/howto.html I would like to see the latest and greatest docs on the main site. Yes, they'll be ahead of the released version, but not by much, and (hopefully) not for long.When the answer to a lot of X doesn't work questions is It's fixed in the trunk, use a snapshot, it would be nice to have the snapshot docs available in a centralized place. This also makes it more fun to contribute to the documentation, because you get to see your work in print right away. Thanks for updating the main site. :) -- 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: Making the current web site suck less
Right, I think confusion is a good word. I approach Maven as an end-user most often, and if I need to dive into a plugin source to finally figure out how it works I do. But, I've had the displeasure of On 3/8/06, John Casey [EMAIL PROTECTED] wrote: +1 Maybe we can put a banner at the top of each page that marks the version it refers to or something. If we styled the reference doco as a manual, it could be part of the page layout that ties it together. I'd be willing to trade a bit of the lookfeel for that sort of information, as it seems to me that it would reduce confusion. -john Tim O'Brien wrote: Having to choose between publishing the latest and greatest docs and only the released version is a problem that Maven seems to have created for itself. Same issue comes up in other projects frequently - Commons has a problem because some of the sites only publish on a release. Latest and greatest are almost never there. What about publishing the latest and greatest docs to another directory? The Maven site gets pushed to a directory that has a version of a label. http://maven.apache.org/version/1.0 , http://maven.apache.org/version/2.0.2, and http://maven.apache.org/version/trunk. This way the Maven site can have a nightly publish of the most current Maven site to Trunk every single day, but still keep legacy docs around intact for people using older versions of the product. The consumer site can point to the latest release, and the developer site can point to trunk. The Maven site plugin would need some mechanism for adding a skin to a site to clearly identify it as Development. On 3/7/06, Wendy Smoak [EMAIL PROTECTED] wrote: On 3/7/06, Brett Porter [EMAIL PROTECTED] wrote: * I'm still a little torn on where plugin docs go. No hurry on this, but something to ponder. We definitely need to make the references for those integrate better. Site/skin inheritance will help No matter where they go, I think they need to be updated more often. Random example... the assembly plugin docs are wrong, and have been that way for months. (it's descriptorId, not maven.assembly.descriptorId.) * http://maven.apache.org/plugins/maven-assembly-plugin/howto.html I would like to see the latest and greatest docs on the main site. Yes, they'll be ahead of the released version, but not by much, and (hopefully) not for long.When the answer to a lot of X doesn't work questions is It's fixed in the trunk, use a snapshot, it would be nice to have the snapshot docs available in a centralized place. This also makes it more fun to contribute to the documentation, because you get to see your work in print right away. Thanks for updating the main site. :) -- 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: Making the current web site suck less
Sorry, gmail confused me and I sent that last one by mistake John. I don't think you'll be trading look and feel here. I think you'd just be doing something like making the site.xml for trunk point to a logo or banner GIF that just added a trunk, draft, or development stamp. If this was done correctly, i think you could add it to the banner graphic in an attractive way. But, it brings up some questions: 1. Would every minor release get a separate site? Or are we just talking about major releases? In other words, is there a 2.x site, or is there a 2.0.2 site?(My vote is for a 2.x site.) 2. What would the first page look like? What would Maven's home page look like? Would it even be managed by Maven? Something to think about is maybe not having the initial Maven page be a Maven site. ASF sites in general seems to be more Developer focused than user focused. What if the initial Maven site were more like the front pages of Mozilla or Rails. An attractive logo, links to resources and materials, an introduction. The home page should be user focused, Maven developers are a minority of the audience here. On 3/8/06, John Casey [EMAIL PROTECTED] wrote: +1 Maybe we can put a banner at the top of each page that marks the version it refers to or something. If we styled the reference doco as a manual, it could be part of the page layout that ties it together. I'd be willing to trade a bit of the lookfeel for that sort of information, as it seems to me that it would reduce confusion. -john Tim O'Brien wrote: Having to choose between publishing the latest and greatest docs and only the released version is a problem that Maven seems to have created for itself. Same issue comes up in other projects frequently - Commons has a problem because some of the sites only publish on a release. Latest and greatest are almost never there. What about publishing the latest and greatest docs to another directory? The Maven site gets pushed to a directory that has a version of a label. http://maven.apache.org/version/1.0 , http://maven.apache.org/version/2.0.2, and http://maven.apache.org/version/trunk. This way the Maven site can have a nightly publish of the most current Maven site to Trunk every single day, but still keep legacy docs around intact for people using older versions of the product. The consumer site can point to the latest release, and the developer site can point to trunk. The Maven site plugin would need some mechanism for adding a skin to a site to clearly identify it as Development. On 3/7/06, Wendy Smoak [EMAIL PROTECTED] wrote: On 3/7/06, Brett Porter [EMAIL PROTECTED] wrote: * I'm still a little torn on where plugin docs go. No hurry on this, but something to ponder. We definitely need to make the references for those integrate better. Site/skin inheritance will help No matter where they go, I think they need to be updated more often. Random example... the assembly plugin docs are wrong, and have been that way for months. (it's descriptorId, not maven.assembly.descriptorId.) * http://maven.apache.org/plugins/maven-assembly-plugin/howto.html I would like to see the latest and greatest docs on the main site. Yes, they'll be ahead of the released version, but not by much, and (hopefully) not for long.When the answer to a lot of X doesn't work questions is It's fixed in the trunk, use a snapshot, it would be nice to have the snapshot docs available in a centralized place. This also makes it more fun to contribute to the documentation, because you get to see your work in print right away. Thanks for updating the main site. :) -- 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: Making the current web site suck less
The problem will be also with reports. Do we need all reports for all releases ? Documentation reports like javadoc, jxr, are needed for each release. But is it useful for quality reports (pmd, simian, linkcheck, ...) ? These reports are useful for the development team to improve their code. But for the end user ??? Arnaud On 3/8/06, Tim O'Brien [EMAIL PROTECTED] wrote: Sorry, gmail confused me and I sent that last one by mistake John. I don't think you'll be trading look and feel here. I think you'd just be doing something like making the site.xml for trunk point to a logo or banner GIF that just added a trunk, draft, or development stamp. If this was done correctly, i think you could add it to the banner graphic in an attractive way. But, it brings up some questions: 1. Would every minor release get a separate site? Or are we just talking about major releases? In other words, is there a 2.x site, or is there a 2.0.2 site?(My vote is for a 2.x site.) 2. What would the first page look like? What would Maven's home page look like? Would it even be managed by Maven? Something to think about is maybe not having the initial Maven page be a Maven site. ASF sites in general seems to be more Developer focused than user focused. What if the initial Maven site were more like the front pages of Mozilla or Rails. An attractive logo, links to resources and materials, an introduction. The home page should be user focused, Maven developers are a minority of the audience here. On 3/8/06, John Casey [EMAIL PROTECTED] wrote: +1 Maybe we can put a banner at the top of each page that marks the version it refers to or something. If we styled the reference doco as a manual, it could be part of the page layout that ties it together. I'd be willing to trade a bit of the lookfeel for that sort of information, as it seems to me that it would reduce confusion. -john Tim O'Brien wrote: Having to choose between publishing the latest and greatest docs and only the released version is a problem that Maven seems to have created for itself. Same issue comes up in other projects frequently - Commons has a problem because some of the sites only publish on a release. Latest and greatest are almost never there. What about publishing the latest and greatest docs to another directory? The Maven site gets pushed to a directory that has a version of a label. http://maven.apache.org/version/1.0 , http://maven.apache.org/version/2.0.2, and http://maven.apache.org/version/trunk. This way the Maven site can have a nightly publish of the most current Maven site to Trunk every single day, but still keep legacy docs around intact for people using older versions of the product. The consumer site can point to the latest release, and the developer site can point to trunk. The Maven site plugin would need some mechanism for adding a skin to a site to clearly identify it as Development. On 3/7/06, Wendy Smoak [EMAIL PROTECTED] wrote: On 3/7/06, Brett Porter [EMAIL PROTECTED] wrote: * I'm still a little torn on where plugin docs go. No hurry on this, but something to ponder. We definitely need to make the references for those integrate better. Site/skin inheritance will help No matter where they go, I think they need to be updated more often. Random example... the assembly plugin docs are wrong, and have been that way for months. (it's descriptorId, not maven.assembly.descriptorId.) * http://maven.apache.org/plugins/maven-assembly-plugin/howto.html I would like to see the latest and greatest docs on the main site. Yes, they'll be ahead of the released version, but not by much, and (hopefully) not for long.When the answer to a lot of X doesn't work questions is It's fixed in the trunk, use a snapshot, it would be nice to have the snapshot docs available in a centralized place. This also makes it more fun to contribute to the documentation, because you get to see your work in print right away. Thanks for updating the main site. :) -- 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: Making the current web site suck less
2006/3/8, Arnaud HERITIER [EMAIL PROTECTED]: The problem will be also with reports. Do we need all reports for all releases ? Documentation reports like javadoc, jxr, are needed for each release. But is it useful for quality reports (pmd, simian, linkcheck, ...) ? These reports are useful for the development team to improve their code. But for the end user ??? For the end user it is an example of the reports that could be done. The first time (maven1) when i saw new reports, i had tried to use them in my project Therefore, checkstyle, javancss, coverage have been used by me because i saw them used by maven. Raphaël
Re: Making the current web site suck less
Comments inline. -john Tim O'Brien wrote: Sorry, gmail confused me and I sent that last one by mistake John. I don't think you'll be trading look and feel here. I think you'd just be doing something like making the site.xml for trunk point to a logo or banner GIF that just added a trunk, draft, or development stamp. If this was done correctly, i think you could add it to the banner graphic in an attractive way. agreed. But, it brings up some questions: 1. Would every minor release get a separate site? Or are we just talking about major releases? In other words, is there a 2.x site, or is there a 2.0.2 site?(My vote is for a 2.x site.) I'd say that since the feature set for minor releases should be stable, there shouldn't be much reason to have separate web sites for each. The documentation (for the most part) shouldn't address pending bugs, or if it does, it should be updated when the next minor release comes out (as in the case of a documented work-around). 2. What would the first page look like? What would Maven's home page look like? Would it even be managed by Maven? Something to think about is maybe not having the initial Maven page be a Maven site. ASF sites in general seems to be more Developer focused than user focused. What if the initial Maven site were more like the front pages of Mozilla or Rails. An attractive logo, links to resources and materials, an introduction. The home page should be user focused, Maven developers are a minority of the audience here. Are you saying that the developer-centric tendency is appropriate for ASF project web sites, then? I'd tend to say that for a product like Maven (not an API, like commons-cli, for instance) it's worth striving to help the user. Since Maven is an Apache product/project, I'd say that having a developer site on a different physical location would be bad...they're different aspects of the same product/project. That said, I think we need to section the developer docs off and put them a click or so in from the main landing page...probably with their own landing page. It's not a simple hierarchy, but then, we have a great deal of variation among our audience members. As these audience members [possibly] transition from users to contributors and so on, we don't want a separation like this to get in their way...there should be *some* cohesiveness, I would think... On 3/8/06, John Casey [EMAIL PROTECTED] wrote: +1 Maybe we can put a banner at the top of each page that marks the version it refers to or something. If we styled the reference doco as a manual, it could be part of the page layout that ties it together. I'd be willing to trade a bit of the lookfeel for that sort of information, as it seems to me that it would reduce confusion. -john Tim O'Brien wrote: Having to choose between publishing the latest and greatest docs and only the released version is a problem that Maven seems to have created for itself. Same issue comes up in other projects frequently - Commons has a problem because some of the sites only publish on a release. Latest and greatest are almost never there. What about publishing the latest and greatest docs to another directory? The Maven site gets pushed to a directory that has a version of a label. http://maven.apache.org/version/1.0 , http://maven.apache.org/version/2.0.2, and http://maven.apache.org/version/trunk. This way the Maven site can have a nightly publish of the most current Maven site to Trunk every single day, but still keep legacy docs around intact for people using older versions of the product. The consumer site can point to the latest release, and the developer site can point to trunk. The Maven site plugin would need some mechanism for adding a skin to a site to clearly identify it as Development. On 3/7/06, Wendy Smoak [EMAIL PROTECTED] wrote: On 3/7/06, Brett Porter [EMAIL PROTECTED] wrote: * I'm still a little torn on where plugin docs go. No hurry on this, but something to ponder. We definitely need to make the references for those integrate better. Site/skin inheritance will help No matter where they go, I think they need to be updated more often. Random example... the assembly plugin docs are wrong, and have been that way for months. (it's descriptorId, not maven.assembly.descriptorId.) * http://maven.apache.org/plugins/maven-assembly-plugin/howto.html I would like to see the latest and greatest docs on the main site. Yes, they'll be ahead of the released version, but not by much, and (hopefully) not for long.When the answer to a lot of X doesn't work questions is It's fixed in the trunk, use a snapshot, it would be nice to have the snapshot docs available in a centralized place. This also makes it more fun to contribute to the documentation, because you get to see your work in print right away. Thanks for updating the main site. :) -- Wendy -
Re: Making the current web site suck less
We already have that in place for the core, the site url is
maven.apache.org/ref/${project.version}/
see
http://svn.apache.org/viewcvs.cgi/maven/components/trunk/pom.xml?rev=382904view=markup
We're missing the continuous integration part to auto deploy site
everytime it's changed
On 3/8/06, Tim O'Brien [EMAIL PROTECTED] wrote:
Having to choose between publishing the latest and greatest docs and only
the released version is a problem that Maven seems to have created for
itself. Same issue comes up in other projects frequently - Commons has a
problem because some of the sites only publish on a release. Latest and
greatest are almost never there.
What about publishing the latest and greatest docs to another directory?
The Maven site gets pushed to a directory that has a version of a
label. http://maven.apache.org/version/1.0
, http://maven.apache.org/version/2.0.2, and
http://maven.apache.org/version/trunk. This way the Maven site can have a
nightly publish of the most current Maven site to Trunk every single day,
but still keep legacy docs around intact for people using older versions of
the product. The consumer site can point to the latest release, and the
developer site can point to trunk. The Maven site plugin would need
some mechanism for adding a skin to a site to clearly identify it as
Development.
On 3/7/06, Wendy Smoak [EMAIL PROTECTED] wrote:
On 3/7/06, Brett Porter [EMAIL PROTECTED] wrote:
* I'm still a little torn on where plugin docs go. No hurry on this, but
something to ponder. We definitely need to make the references for those
integrate better. Site/skin inheritance will help
No matter where they go, I think they need to be updated more often.
Random example... the assembly plugin docs are wrong, and have been
that way for months. (it's descriptorId, not
maven.assembly.descriptorId.)
* http://maven.apache.org/plugins/maven-assembly-plugin/howto.html
I would like to see the latest and greatest docs on the main site.
Yes, they'll be ahead of the released version, but not by much, and
(hopefully) not for long.When the answer to a lot of X doesn't work
questions is It's fixed in the trunk, use a snapshot, it would be
nice to have the snapshot docs available in a centralized place.
This also makes it more fun to contribute to the documentation,
because you get to see your work in print right away.
Thanks for updating the main site. :)
--
Wendy
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
--
I could give you my word as a Spaniard.
No good. I've known too many Spaniards.
-- The Princess Bride
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
Re: Making the current web site suck less
Good to see discussion on this. I'll choose more controversial topics next time, because I've already discussed this with myself at length on this list. As I've said recently, I'm just waiting for 2.0.3 to my plan into action. - Brett Tim O'Brien wrote: Having to choose between publishing the latest and greatest docs and only the released version is a problem that Maven seems to have created for itself. Same issue comes up in other projects frequently - Commons has a problem because some of the sites only publish on a release. Latest and greatest are almost never there. What about publishing the latest and greatest docs to another directory? The Maven site gets pushed to a directory that has a version of a label. http://maven.apache.org/version/1.0 , http://maven.apache.org/version/2.0.2, and http://maven.apache.org/version/trunk. This way the Maven site can have a nightly publish of the most current Maven site to Trunk every single day, but still keep legacy docs around intact for people using older versions of the product. The consumer site can point to the latest release, and the developer site can point to trunk. The Maven site plugin would need some mechanism for adding a skin to a site to clearly identify it as Development. On 3/7/06, Wendy Smoak [EMAIL PROTECTED] wrote: On 3/7/06, Brett Porter [EMAIL PROTECTED] wrote: * I'm still a little torn on where plugin docs go. No hurry on this, but something to ponder. We definitely need to make the references for those integrate better. Site/skin inheritance will help No matter where they go, I think they need to be updated more often. Random example... the assembly plugin docs are wrong, and have been that way for months. (it's descriptorId, not maven.assembly.descriptorId.) * http://maven.apache.org/plugins/maven-assembly-plugin/howto.html I would like to see the latest and greatest docs on the main site. Yes, they'll be ahead of the released version, but not by much, and (hopefully) not for long.When the answer to a lot of X doesn't work questions is It's fixed in the trunk, use a snapshot, it would be nice to have the snapshot docs available in a centralized place. This also makes it more fun to contribute to the documentation, because you get to see your work in print right away. Thanks for updating the main site. :) -- 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: Making the current web site suck less
That separates the core site, but there is still a two issues, and,
unfortunately, I'm not sure if there is an easy way to address it.
First, it is easy to publish specific versions of projects to different
directories. But, the Maven documentation consists of a bunch of related
sites. I think the main challenge is Maven plug-in sites and making sure
that all external links from one version of Maven link to the appropriate
version of another site. Here's where it would be helpful to be able to
provide URL prefixes for outbound links. Instead of linking to a specific
URL.
Second, (and correct me if I'm wrong), a Maven version is just a String.
There is no concept in a the POM of a Major vs. a Minor release. So,
although there's seems to be agreement that it doesn't make much sense to
publish a new version of the site for each minor revision, that might not be
possible without adding that concept to Maven (unlikely) or just coding
/ref/2 for a 2.x version instead of using the logic. So while the
replacement logic you have for core is good, it would create a new Maven
site for each minor version release. Maybe that's OK?
On 3/8/06, Carlos Sanchez [EMAIL PROTECTED] wrote:
We already have that in place for the core, the site url is
maven.apache.org/ref/${project.version}/
see
http://svn.apache.org/viewcvs.cgi/maven/components/trunk/pom.xml?rev=382904view=markup
We're missing the continuous integration part to auto deploy site
everytime it's changed
On 3/8/06, Tim O'Brien [EMAIL PROTECTED] wrote:
Having to choose between publishing the latest and greatest docs and
only
the released version is a problem that Maven seems to have created for
itself. Same issue comes up in other projects frequently - Commons has
a
problem because some of the sites only publish on a release. Latest and
greatest are almost never there.
What about publishing the latest and greatest docs to another directory?
The Maven site gets pushed to a directory that has a version of a
label. http://maven.apache.org/version/1.0
, http://maven.apache.org/version/2.0.2, and
http://maven.apache.org/version/trunk. This way the Maven site can have
a
nightly publish of the most current Maven site to Trunk every single
day,
but still keep legacy docs around intact for people using older versions
of
the product. The consumer site can point to the latest release, and
the
developer site can point to trunk. The Maven site plugin would need
some mechanism for adding a skin to a site to clearly identify it as
Development.
On 3/7/06, Wendy Smoak [EMAIL PROTECTED] wrote:
On 3/7/06, Brett Porter [EMAIL PROTECTED] wrote:
* I'm still a little torn on where plugin docs go. No hurry on this,
but
something to ponder. We definitely need to make the references for
those
integrate better. Site/skin inheritance will help
No matter where they go, I think they need to be updated more often.
Random example... the assembly plugin docs are wrong, and have been
that way for months. (it's descriptorId, not
maven.assembly.descriptorId.)
* http://maven.apache.org/plugins/maven-assembly-plugin/howto.html
I would like to see the latest and greatest docs on the main site.
Yes, they'll be ahead of the released version, but not by much, and
(hopefully) not for long.When the answer to a lot of X doesn't work
questions is It's fixed in the trunk, use a snapshot, it would be
nice to have the snapshot docs available in a centralized place.
This also makes it more fun to contribute to the documentation,
because you get to see your work in print right away.
Thanks for updating the main site. :)
--
Wendy
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
--
I could give you my word as a Spaniard.
No good. I've known too many Spaniards.
-- The Princess Bride
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
Re: Making the current web site suck less
On 3/8/06, John Casey [EMAIL PROTECTED] wrote: snip Something to think about is maybe not having the initial Maven page be a Maven site. ASF sites in general seems to be more Developer focused than user focused. What if the initial Maven site were more like the front pages of Mozilla or Rails. An attractive logo, links to resources and materials, an introduction. The home page should be user focused, Maven developers are a minority of the audience here. Are you saying that the developer-centric tendency is appropriate for ASF project web sites, then? I'd tend to say that for a product like Maven (not an API, like commons-cli, for instance) it's worth striving to help the user. Since Maven is an Apache product/project, I'd say that having a developer site on a different physical location would be bad...they're different aspects of the same product/project. That said, I think we need to section the developer docs off and put them a click or so in from the main landing page...probably with their own landing page. I think I agree with you. When I said developer-centric I meant apache-developer-centric. IMO, more projects need to think about the user who has 30 seconds to figure out the best way to download/use Derby. The current Maven site has too many links, too much distracting people from what should be a simple message - Download Maven, you won't believe how you developed without it. We promise..I'm not saying that we should all become marketing people, but it's something to consider. It's not a simple hierarchy, but then, we have a great deal of variation among our audience members. As these audience members [possibly] transition from users to contributors and so on, we don't want a separation like this to get in their way...there should be *some* cohesiveness, I would think... I'm not saying this to be contrary, bear with me: most people that use Maven don't care to know much about the internals or how it is being developed. They simply want to download a product that works, is well documented, and use it. A small minority of those users will get an itch that needs to be scratched or decide that the gift of free software should be repaid by involvement in a community. So, if you wrote up a survey, and quizzed people who use Maven every day, I think you'd probably find that most of them think Jason van Zyl is a famous magician and the Meritocracy is a spell in Dungeons and Dragons. I'm not saying this as a cynical jibe, but to make the point that regardless of the Maven website, we will always about an equal mix - out of 100 - 95 people download Maven, 5 subscribe to the users list for a week, maybe 4 ask questions on the user list, and, if you are lucky, 1 submits a patch. And even that's overestimating, apply that forumla to the httpd project and it would have 10^5 patches submitted per year. Turn your statement around. audience members [possibly] transition form users to contributors. Assume that a simpler user focused launch page made it easier for people to adopt Maven. If this separation of user-focused and developer-focused documentation increases the population of users, we've increase the pool of potential contributors. I'm betting on the fact that as users root around the documentation, they'll catch on to the fact that this is the ASF they will pick up the community. I think a good strategy is to make the landing page for Maven as simple as possible, with a good short sell, as little text as possible, link to download, and some news and announcements. The Maven launch page should be very similar to the Mozilla launch page - there are still links to the developer pages. Instead we've got a link named Netbeans Module, a link on the top of the page to Maven followed by a link to Maven 2.x and Maven 1.x. All the links have a 20% change of having a completely different skin. There are links to a Wiki and external sites that are not labeled as such. There is a Project Team report (http://maven.apache.org/team-list.html) that doesn't list have of the people involved in Maven. Did you know there are no contributors to the Maven project and that there are only 8 people working on Maven? For some reason, I know what the Actual Time is for all the people on the project team down to the second (I've never figured the need for that field out), but good luck customizing the team-list support. :-) Here's another good one, click on a Guide, then click on the banner logo. That links back to /guide, click on the same banner logo, that links back to the home page. The Maven site is full of these inconsistencies, and it's not something that people can just fix with patches. IMO, the site plugin needs serious rework. It doesn't create good web sites, especially for multi-projects. I guess I've just pissed off the Maven development team by telling all of you that Maven doesn't do a good job of creating web sites for users. There,
Re: Making the current web site suck less
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 All in all, I'd have to agree with the sentiments of this. I don't think anything should be taken personally although I know some personalities might be inclined to react emotionally at the words used, but if you look at the sentiment I believe it's right on. Your users may be developers, but not necessarily for your project. Treat them to a 'user' site. Brian Tim O'Brien wrote: On 3/8/06, John Casey [EMAIL PROTECTED] wrote: snip Something to think about is maybe not having the initial Maven page be a Maven site. ASF sites in general seems to be more Developer focused than user focused. What if the initial Maven site were more like the front pages of Mozilla or Rails. An attractive logo, links to resources and materials, an introduction. The home page should be user focused, Maven developers are a minority of the audience here. Are you saying that the developer-centric tendency is appropriate for ASF project web sites, then? I'd tend to say that for a product like Maven (not an API, like commons-cli, for instance) it's worth striving to help the user. Since Maven is an Apache product/project, I'd say that having a developer site on a different physical location would be bad...they're different aspects of the same product/project. That said, I think we need to section the developer docs off and put them a click or so in from the main landing page...probably with their own landing page. I think I agree with you. When I said developer-centric I meant apache-developer-centric. IMO, more projects need to think about the user who has 30 seconds to figure out the best way to download/use Derby. The current Maven site has too many links, too much distracting people from what should be a simple message - Download Maven, you won't believe how you developed without it. We promise..I'm not saying that we should all become marketing people, but it's something to consider. It's not a simple hierarchy, but then, we have a great deal of variation among our audience members. As these audience members [possibly] transition from users to contributors and so on, we don't want a separation like this to get in their way...there should be *some* cohesiveness, I would think... I'm not saying this to be contrary, bear with me: most people that use Maven don't care to know much about the internals or how it is being developed. They simply want to download a product that works, is well documented, and use it. A small minority of those users will get an itch that needs to be scratched or decide that the gift of free software should be repaid by involvement in a community. So, if you wrote up a survey, and quizzed people who use Maven every day, I think you'd probably find that most of them think Jason van Zyl is a famous magician and the Meritocracy is a spell in Dungeons and Dragons. I'm not saying this as a cynical jibe, but to make the point that regardless of the Maven website, we will always about an equal mix - out of 100 - 95 people download Maven, 5 subscribe to the users list for a week, maybe 4 ask questions on the user list, and, if you are lucky, 1 submits a patch. And even that's overestimating, apply that forumla to the httpd project and it would have 10^5 patches submitted per year. Turn your statement around. audience members [possibly] transition form users to contributors. Assume that a simpler user focused launch page made it easier for people to adopt Maven. If this separation of user-focused and developer-focused documentation increases the population of users, we've increase the pool of potential contributors. I'm betting on the fact that as users root around the documentation, they'll catch on to the fact that this is the ASF they will pick up the community. I think a good strategy is to make the landing page for Maven as simple as possible, with a good short sell, as little text as possible, link to download, and some news and announcements. The Maven launch page should be very similar to the Mozilla launch page - there are still links to the developer pages. Instead we've got a link named Netbeans Module, a link on the top of the page to Maven followed by a link to Maven 2.x and Maven 1.x. All the links have a 20% change of having a completely different skin. There are links to a Wiki and external sites that are not labeled as such. There is a Project Team report (http://maven.apache.org/team-list.html) that doesn't list have of the people involved in Maven. Did you know there are no contributors to the Maven project and that there are only 8 people working on Maven? For some reason, I know what the Actual Time is for all the people on the project team down to the second (I've never figured the need for that field out), but good luck customizing the team-list support. :-) Here's another good one, click on a Guide, then click on
Re: Making the current web site suck less
I think what everyone is saying sounds more or less correct, but what is the solution then? If they can't rely on a runtime container to host the site, options become MUCH more limited. Complaints about the UI are fine and I'm sure everyone welcomes them, but possible solutions that fit into the requirements of the projects technical constraints are much more helpful :) I can't think of any really good solutions off the top of my head that don't rely on runtime stuff? On 3/9/06, Brian K. Wallace [EMAIL PROTECTED] wrote: -BEGIN PGP SIGNED MESSAGE- Hash: SHA1 All in all, I'd have to agree with the sentiments of this. I don't think anything should be taken personally although I know some personalities might be inclined to react emotionally at the words used, but if you look at the sentiment I believe it's right on. Your users may be developers, but not necessarily for your project. Treat them to a 'user' site. Brian Tim O'Brien wrote: On 3/8/06, John Casey [EMAIL PROTECTED] wrote: snip Something to think about is maybe not having the initial Maven page be a Maven site. ASF sites in general seems to be more Developer focused than user focused. What if the initial Maven site were more like the front pages of Mozilla or Rails. An attractive logo, links to resources and materials, an introduction. The home page should be user focused, Maven developers are a minority of the audience here. Are you saying that the developer-centric tendency is appropriate for ASF project web sites, then? I'd tend to say that for a product like Maven (not an API, like commons-cli, for instance) it's worth striving to help the user. Since Maven is an Apache product/project, I'd say that having a developer site on a different physical location would be bad...they're different aspects of the same product/project. That said, I think we need to section the developer docs off and put them a click or so in from the main landing page...probably with their own landing page. I think I agree with you. When I said developer-centric I meant apache-developer-centric. IMO, more projects need to think about the user who has 30 seconds to figure out the best way to download/use Derby. The current Maven site has too many links, too much distracting people from what should be a simple message - Download Maven, you won't believe how you developed without it. We promise..I'm not saying that we should all become marketing people, but it's something to consider. It's not a simple hierarchy, but then, we have a great deal of variation among our audience members. As these audience members [possibly] transition from users to contributors and so on, we don't want a separation like this to get in their way...there should be *some* cohesiveness, I would think... I'm not saying this to be contrary, bear with me: most people that use Maven don't care to know much about the internals or how it is being developed. They simply want to download a product that works, is well documented, and use it. A small minority of those users will get an itch that needs to be scratched or decide that the gift of free software should be repaid by involvement in a community. So, if you wrote up a survey, and quizzed people who use Maven every day, I think you'd probably find that most of them think Jason van Zyl is a famous magician and the Meritocracy is a spell in Dungeons and Dragons. I'm not saying this as a cynical jibe, but to make the point that regardless of the Maven website, we will always about an equal mix - out of 100 - 95 people download Maven, 5 subscribe to the users list for a week, maybe 4 ask questions on the user list, and, if you are lucky, 1 submits a patch. And even that's overestimating, apply that forumla to the httpd project and it would have 10^5 patches submitted per year. Turn your statement around. audience members [possibly] transition form users to contributors. Assume that a simpler user focused launch page made it easier for people to adopt Maven. If this separation of user-focused and developer-focused documentation increases the population of users, we've increase the pool of potential contributors. I'm betting on the fact that as users root around the documentation, they'll catch on to the fact that this is the ASF they will pick up the community. I think a good strategy is to make the landing page for Maven as simple as possible, with a good short sell, as little text as possible, link to download, and some news and announcements. The Maven launch page should be very similar to the Mozilla launch page - there are still links to the developer pages. Instead we've got a link named Netbeans Module, a link on the top of the page to Maven followed by a link to Maven 2.x and Maven 1.x. All the links have a 20% change of
Re: Making the current web site suck less
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Jesse Kuhnert wrote: I think what everyone is saying sounds more or less correct, but what is the solution then? If they can't rely on a runtime container to host the site, options become MUCH more limited. Complaints about the UI are fine and I'm sure everyone welcomes them, but possible solutions that fit into the requirements of the projects technical constraints are much more helpful :) I can't think of any really good solutions off the top of my head that don't rely on runtime stuff? In thinking about what a runtime container would provide, I can't think of anything required on a site with no user-login / form / etc that would require any sort of container. I, personally, think maven-site does an adequate job for sites that only a developer could love. To illustrate both my point that a runtime container isn't necessary for the information necessary, and a site that's more user-geared I suggest a look at Geronimo's new look (http://geronimo.apache.org). I'm not saying it's perfect - it's closer to Maven's current site than a Mozilla site - but it's definitely more user oriented/friendly - and to the best of my knowledge runs outside of a container. The difference? That site was designed. Maven generates sites that are coded. (And I'm not talking about pretty - more the concise look and user-level links.) And that's more of a 'content designed' than a 'look and feel' design. Then there's the content debate... Getting Started with Maven goes on _forever_. To get started?!? And that's entirely outside the scope of the documentation link (which doesn't quite go on forever - just links forever). And the first link on documentation? Getting Started. [and NO, I'm not saying there's too much documentation now ;-)] My thoughts. Other's (and sometimes mine) may vary. -BEGIN PGP SIGNATURE- Version: GnuPG v1.2.5 (MingW32) iD8DBQFED84VaCoPKRow/gARAiWWAJ9dUNVLKI8b32vDJVCj+axp/KTlrwCfdbxP yipbhAFs4+YTKZWo9ZX2BX4= =yYGS -END PGP SIGNATURE- - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Making the current web site suck less
On 3/9/06, Brian K. Wallace [EMAIL PROTECTED] wrote: -BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Jesse Kuhnert wrote: I think what everyone is saying sounds more or less correct, but what is the solution then? If they can't rely on a runtime container to host the site, options become MUCH more limited. Complaints about the UI are fine and I'm sure everyone welcomes them, but possible solutions that fit into the requirements of the projects technical constraints are much more helpful :) I can't think of any really good solutions off the top of my head that don't rely on runtime stuff? In thinking about what a runtime container would provide, I can't think of anything required on a site with no user-login / form / etc that would require any sort of container. I, personally, think maven-site does an adequate job for sites that only a developer could love. To illustrate both my point that a runtime container isn't necessary for the information necessary, and a site that's more user-geared I suggest a look at Geronimo's new look (http://geronimo.apache.org). I'm not saying it's perfect - it's closer to Maven's current site than a Mozilla site - but it's definitely more user oriented/friendly - and to the best of my knowledge runs outside of a container. The difference? That site was designed. Maven generates sites that are coded. (And I'm not talking about pretty - more the concise look and user-level links.) And that's more of a 'content designed' than a 'look and feel' design. I read your response, clicked on the Geronimo site, and wanted to believe that that was possible with Maven. But, if you look at https://svn.apache.org/repos/asf/geronimo/site/ It's either Maven 1.x or Ant the directory contains a v3 POM, but it also contains an . The NOTES.txt begins Download Ant from http://ant.apache.org;.
Re: Making the current web site suck less
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 It uses anakia to transform, but in true Maven spirit it should be able to be done - with a plugin. ;-) And maybe maven-site is suited to it just fine (not a maven-site expert for user sites AT ALL - I'm with Jesse here that so much more 'whiz-bang' is possible with a container. add a db and the ability to submit plugin information, have it approved and be live, searchable by name, keyword, etc, and have paged tables for results would do wonders in my eyes) and all that needs to be done is enhance the plugin and change the site source and sprinkle generously with css. My main point was content geared, though. As a user of a project, there are usually about 4 main links I look for: 1. Documentation - tell me why it fits or won't fit my needs and how to get my job done. If you've got layers/levels of documentation, break it down in there. 2. Download - Okay. If I hadn't heard by word of mouth, I found out in the documentation why it's great. Let me get it. Have different versions? I should be able to find them all on the Download page, right? 3. Plugins/Extensions - The project is great, but aside from doing nothing I need to be able to so other stuff. What's out there that I can use? Consider Plugins/Extensions as cyclic to the main page. Give me documentation. Give me a way to download it. If you can 'extend' it, tell me what extensions there are for it. Then give me a way to find help. 4. Support - HELP! My boss is standing over my shoulder and this thing isn't working!!! (nevermind that I skipped that part of the docs, where's the support?) Mailing Lists? It's in there. Forum? It's in there. Wiki? It's in there. What I see on the Maven site is: Features - sounds like boasts, but that's what projects do, right? Start with #1: Simple project setup that follows best practices - get a new project or module started in seconds. Leads me to the Getting Started link which is a mile long. Somewhere in there my reading skills must have drastically improved to be able to read all that getting started material and still get a project started in seconds. A user FAQ that has a lot of we need more information answers Where is it - Where's Maven? Nope. Short page with links to maven structures - pretty long pages, too; and mailing list archives? Specific Plugin references and a single Reference link that takes me inside 'current' and looks nothing like anything else on the main page. About Maven 2.0 - Wait - I'm on the maven site and the first I see on the main page about a Maven 2 is half way down the nav on the left - or up on the top right. But the top right has Maven, Maven 1.x, and Maven 2.x. Why this hooplah about Maven 2 and users of Maven 1? I'm not here for either of those - I'm here for Maven. On the bright side, there's a FAQ under this section that's really a FAQ. Powered By - I view this as a selling point to a small extent, but the resulting page is pretty... lame? [why must there always be at least one page with work in progress on it?] FAQ for Other Projects: Huh? Does this sound like the place to find a FAQ on Drupal? Spring, maybe? Oh.. nope. Don't get it. Not on the main page. And the dreaded Project Documentation section. Nice for developers. More than a little meaningless to users by and large. And to make matters worse in this instance, it's project documentation for maven-site - a Maven plugin! How confusing is that?!? These are points I see from a 'user' point of view of the site. There's a LOT of information on the site - some has to be 'fixed' or 'finished' or 'redone', but there's a lot there. And there needs to be more - too many things about Maven are plugin specific and not documented for users to understand. But if it's not organized, it'll still be next to useless for a user to understand. Could this be done with Maven itself and a plugin (be it maven-site or something else)? Well... if Maven can do everything else it does, I don't see why not. (not as easily as other ways, perhaps... but still possible) Tim O'Brien wrote: I read your response, clicked on the Geronimo site, and wanted to believe that that was possible with Maven. But, if you look at https://svn.apache.org/repos/asf/geronimo/site/ It's either Maven 1.x or Ant the directory contains a v3 POM, but it also contains an . The NOTES.txt begins Download Ant from http://ant.apache.org;. -BEGIN PGP SIGNATURE- Version: GnuPG v1.2.5 (MingW32) iD8DBQFED9zDaCoPKRow/gARAvBoAJ94VrB1h7xymX+GjcUtOA9wLVFMXACgtOIh qLaOSU94wFMYKdicCTV7P/c= =Sk/2 -END PGP SIGNATURE- - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Making the current web site suck less
On 3/7/06, Brett Porter [EMAIL PROTECTED] wrote: * I'm still a little torn on where plugin docs go. No hurry on this, but something to ponder. We definitely need to make the references for those integrate better. Site/skin inheritance will help No matter where they go, I think they need to be updated more often. Random example... the assembly plugin docs are wrong, and have been that way for months. (it's descriptorId, not maven.assembly.descriptorId.) * http://maven.apache.org/plugins/maven-assembly-plugin/howto.html I would like to see the latest and greatest docs on the main site. Yes, they'll be ahead of the released version, but not by much, and (hopefully) not for long.When the answer to a lot of X doesn't work questions is It's fixed in the trunk, use a snapshot, it would be nice to have the snapshot docs available in a centralized place. This also makes it more fun to contribute to the documentation, because you get to see your work in print right away. Thanks for updating the main site. :) -- Wendy - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Making the current web site suck less
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Wendy Smoak wrote: On 3/7/06, Brett Porter [EMAIL PROTECTED] wrote: * I'm still a little torn on where plugin docs go. No hurry on this, but something to ponder. We definitely need to make the references for those integrate better. Site/skin inheritance will help No matter where they go, I think they need to be updated more often. Random example... the assembly plugin docs are wrong, and have been that way for months. (it's descriptorId, not maven.assembly.descriptorId.) * http://maven.apache.org/plugins/maven-assembly-plugin/howto.html I would like to see the latest and greatest docs on the main site. Yes, they'll be ahead of the released version, but not by much, and (hopefully) not for long.When the answer to a lot of X doesn't work questions is It's fixed in the trunk, use a snapshot, it would be nice to have the snapshot docs available in a centralized place. This also makes it more fun to contribute to the documentation, because you get to see your work in print right away. Thanks for updating the main site. :) -- Wendy While I agree that it would be nice to have the 'latest and greatest' docs on the main site, I don't believe having them as the only documentation is a good idea at all. The documentation should be able to evolve after a release to make them better, but having documentation online that applies to trunk code and not released code tends to equate bad documentation (the docs say I can do X. oh, that's in the trunk, use a snapshot). If you aren't going to have two sets - one for released code and one for trunk code, only go with released code. If there are changes that can be made to make the released code's documentation better between releases, by all means - make it live as soon as practical. My .02 Brian -BEGIN PGP SIGNATURE- Version: GnuPG v1.2.5 (MingW32) iD8DBQFEDjrpaCoPKRow/gARAiGlAJ98kZI0ItEEusrpmgIAT/jaQBaLXgCfbUhi 8iPFWc+Loyp9VtbXHxd6eqY= =cs6U -END PGP SIGNATURE- - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Making the current web site suck less
Since we talk about 'latest and greatest', I wonder why javadocs published online cannot serve as 'latest and greatest' docs? I am +1 to Carlos' idea about documenting almost all methods. If we were to publish API docs for Maven and Plugins on the website (some separate URL) with every Maven release build or every nightly build, at least they would always reflect the 'latest and greatest' for the code. Cheers, Rahul Brian K. Wallace wrote: -BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Wendy Smoak wrote: On 3/7/06, Brett Porter [EMAIL PROTECTED] wrote: * I'm still a little torn on where plugin docs go. No hurry on this, but something to ponder. We definitely need to make the references for those integrate better. Site/skin inheritance will help No matter where they go, I think they need to be updated more often. Random example... the assembly plugin docs are wrong, and have been that way for months. (it's descriptorId, not maven.assembly.descriptorId.) * http://maven.apache.org/plugins/maven-assembly-plugin/howto.html I would like to see the latest and greatest docs on the main site. Yes, they'll be ahead of the released version, but not by much, and (hopefully) not for long.When the answer to a lot of X doesn't work questions is It's fixed in the trunk, use a snapshot, it would be nice to have the snapshot docs available in a centralized place. This also makes it more fun to contribute to the documentation, because you get to see your work in print right away. Thanks for updating the main site. :) -- Wendy While I agree that it would be nice to have the 'latest and greatest' docs on the main site, I don't believe having them as the only documentation is a good idea at all. The documentation should be able to evolve after a release to make them better, but having documentation online that applies to trunk code and not released code tends to equate bad documentation (the docs say I can do X. oh, that's in the trunk, use a snapshot). If you aren't going to have two sets - one for released code and one for trunk code, only go with released code. If there are changes that can be made to make the released code's documentation better between releases, by all means - make it live as soon as practical. My .02 Brian -BEGIN PGP SIGNATURE- Version: GnuPG v1.2.5 (MingW32) iD8DBQFEDjrpaCoPKRow/gARAiGlAJ98kZI0ItEEusrpmgIAT/jaQBaLXgCfbUhi 8iPFWc+Loyp9VtbXHxd6eqY= =cs6U -END PGP SIGNATURE- - 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: Making the current web site suck less
On 3/7/06, Brian K. Wallace [EMAIL PROTECTED] wrote: While I agree that it would be nice to have the 'latest and greatest' docs on the main site, I don't believe having them as the only documentation is a good idea at all. The documentation should be able to evolve after a release to make them better, After it's tagged and rolled, it's done. The docs for that release (as in 1.0beta3) aren't going to change. Anything that gets added or fixed belongs to the next release. The situation now is that if an error in the plugin docs is found, it stays on the site until the next release happens. but having documentation online that applies to trunk code and not released code tends to equate bad documentation (the docs say I can do X. oh, that's in the trunk, use a snapshot). So it's better to never even know that X was possible? Meanwhile the user thinks Maven is missing features and constructs a workaround, or gives up. If the version number showed up on the plugin docs (it used to...) and the documentation said since x.x on new features, I'm pretty sure people could figure it out. I don't understand why visible new features and use a snapshot equates to bad documentation. I don't want to sit around perfecting the documentation for the *last* release, I want to keep moving forward with the latest bits. -- Wendy - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Making the current web site suck less
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Wendy Smoak wrote: On 3/7/06, Brian K. Wallace [EMAIL PROTECTED] wrote: While I agree that it would be nice to have the 'latest and greatest' docs on the main site, I don't believe having them as the only documentation is a good idea at all. The documentation should be able to evolve after a release to make them better, After it's tagged and rolled, it's done. The docs for that release (as in 1.0beta3) aren't going to change. Anything that gets added or fixed belongs to the next release. The situation now is that if an error in the plugin docs is found, it stays on the site until the next release happens. My point was centered on the only, not at all. but having documentation online that applies to trunk code and not released code tends to equate bad documentation (the docs say I can do X. oh, that's in the trunk, use a snapshot). So it's better to never even know that X was possible? If X isn't possible in the last release... ? Meanwhile the user thinks Maven is missing features and constructs a workaround, or gives up. If the version number showed up on the plugin docs (it used to...) and the documentation said since x.x on new features, I'm pretty sure people could figure it out. I don't understand why visible new features and use a snapshot equates to bad documentation. I don't want to sit around perfecting the documentation for the *last* release, I want to keep moving forward with the latest bits. I wasn't meaning to say documentation work only happens for the *last* release. Just that having 'bleeding edge' documentation as _the_ documentation doesn't help users if it doesn't match the released code they have. -BEGIN PGP SIGNATURE- Version: GnuPG v1.2.5 (MingW32) iD8DBQFEDkoYaCoPKRow/gARAoaHAKCAnLNKhH1w//Kr5Qb7CdiWOzh9RgCdF1sc gdXE6eGMoKjtCGZldKyu+/E= =weEY -END PGP SIGNATURE- - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Making the current web site suck less
They are already there http://maven.apache.org/ref/current/index.html Note the new Reference link in the left menu On 3/7/06, Rinku [EMAIL PROTECTED] wrote: Since we talk about 'latest and greatest', I wonder why javadocs published online cannot serve as 'latest and greatest' docs? I am +1 to Carlos' idea about documenting almost all methods. If we were to publish API docs for Maven and Plugins on the website (some separate URL) with every Maven release build or every nightly build, at least they would always reflect the 'latest and greatest' for the code. Cheers, Rahul Brian K. Wallace wrote: -BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Wendy Smoak wrote: On 3/7/06, Brett Porter [EMAIL PROTECTED] wrote: * I'm still a little torn on where plugin docs go. No hurry on this, but something to ponder. We definitely need to make the references for those integrate better. Site/skin inheritance will help No matter where they go, I think they need to be updated more often. Random example... the assembly plugin docs are wrong, and have been that way for months. (it's descriptorId, not maven.assembly.descriptorId.) * http://maven.apache.org/plugins/maven-assembly-plugin/howto.html I would like to see the latest and greatest docs on the main site. Yes, they'll be ahead of the released version, but not by much, and (hopefully) not for long.When the answer to a lot of X doesn't work questions is It's fixed in the trunk, use a snapshot, it would be nice to have the snapshot docs available in a centralized place. This also makes it more fun to contribute to the documentation, because you get to see your work in print right away. Thanks for updating the main site. :) -- Wendy While I agree that it would be nice to have the 'latest and greatest' docs on the main site, I don't believe having them as the only documentation is a good idea at all. The documentation should be able to evolve after a release to make them better, but having documentation online that applies to trunk code and not released code tends to equate bad documentation (the docs say I can do X. oh, that's in the trunk, use a snapshot). If you aren't going to have two sets - one for released code and one for trunk code, only go with released code. If there are changes that can be made to make the released code's documentation better between releases, by all means - make it live as soon as practical. My .02 Brian -BEGIN PGP SIGNATURE- Version: GnuPG v1.2.5 (MingW32) iD8DBQFEDjrpaCoPKRow/gARAiGlAJ98kZI0ItEEusrpmgIAT/jaQBaLXgCfbUhi 8iPFWc+Loyp9VtbXHxd6eqY= =cs6U -END PGP SIGNATURE- - 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] -- I could give you my word as a Spaniard. No good. I've known too many Spaniards. -- The Princess Bride - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
