You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@maven.apache.org by Brett Porter <br...@apache.org> on 2006/03/07 23:17:58 UTC
Making the current web site suck less
Ok, something more practical right now. I'd meant to bring it up at the
same time as my other mail, but thanks to Jesse for reminding me.
I'm embarrassed to say that the front page looks a whole lot like the
one I created about this time last year for 2.0 alpha 1. I think it
needs an update. IMO, the front page should be:
* an introduction
* an explanation of what all the links on the left are
* where to find information
* quick links like the download box
* have news, but not be the primary focus of the page
* above all, brief.
What do others think?
I think we need to revisit the navigation too. We have a couple of rogue
elements and its a bit hard to see anything. We especially need to stop
the titles wrapping.
I'd propose:
Get Maven
* Download
* Release Notes
About Maven
* What is Maven?
* Features
* FAQ
* Powered By
Documentation
* Getting Started
* User Guide
* Where is it?
* Plugin Reference
Reference
* API Reference
* Source Code XRef
IDE Integration
* Eclipse Extension
* Netbeans Module
Contributing
* How to Help
* User contributed FAQ
* FAQ for Other Projects (rename this)
Other things:
* I think the FAQ structure should be revised. They are really old too.
Maybe one master FAQ for "things to know about the maven project" rather
than technical questions, then push detailed FAQs into sections of the
documentation
* 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.
* 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
* Need to make the other updates regarding reference material/dev
subsite that I proposed separately. I think everyone is sick of my
mails, so I'll JFDI after 2.0.3 :)
* Need to apply same principles to other subsites (Continuum, etc).
- Brett
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Making the current web site suck less
Posted by Brett Porter <br...@apache.org>.
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/%3C440E0696.9090604@apache.org%3E
- Brett
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Making the current web site suck less
Posted by Piéroni Raphaël <ra...@gmail.com>.
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 <br...@apache.org>:
>
> 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 <br...@apache.org>:
> >> 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: dev-unsubscribe@maven.apache.org
> >>> For additional commands, e-mail: dev-help@maven.apache.org
> >>>
> >> ---------------------------------------------------------------------
> >> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> >> For additional commands, e-mail: dev-help@maven.apache.org
> >>
> >>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
>
Re: Making the current web site suck less
Posted by Raphaël Piéroni <ra...@gmail.com>.
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: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Making the current web site suck less
Posted by Brett Porter <br...@apache.org>.
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 <br...@apache.org>:
>> 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: dev-unsubscribe@maven.apache.org
>>> For additional commands, e-mail: dev-help@maven.apache.org
>>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
>> For additional commands, e-mail: dev-help@maven.apache.org
>>
>>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Making the current web site suck less
Posted by Piéroni Raphaël <ra...@gmail.com>.
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 <br...@apache.org>:
>
> 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: dev-unsubscribe@maven.apache.org
> > For additional commands, e-mail: dev-help@maven.apache.org
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
>
Re: Making the current web site suck less
Posted by Brett Porter <br...@apache.org>.
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: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Making the current web site suck less
Posted by Tim O'Brien <to...@discursive.com>.
On 3/9/06, Brett Porter <br...@apache.org> 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: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
>
Re: Making the current web site suck less
Posted by Brett Porter <br...@apache.org>.
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: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Making the current web site suck less
Posted by Brett Porter <br...@apache.org>.
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: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Making the current web site suck less
Posted by Raphaël Piéroni <ra...@gmail.com>.
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: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Making the current web site suck less
Posted by Piéroni Raphaël <ra...@gmail.com>.
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 <ra...@gmail.com>:
>
> 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
Posted by Piéroni Raphaël <ra...@gmail.com>.
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
Posted by "Brian K. Wallace" <br...@transmorphix.com>.
-----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? Ohhhhh...... 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: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Making the current web site suck less
Posted by Tim O'Brien <to...@discursive.com>.
On 3/9/06, Brian K. Wallace <br...@transmorphix.com> 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
Posted by "Brian K. Wallace" <br...@transmorphix.com>.
-----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: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Making the current web site suck less
Posted by Jesse Kuhnert <jk...@gmail.com>.
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 <br...@transmorphix.com> 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 <jd...@yahoo.com> 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, I said it. Maven creates so-so web sites for developers,
> but
> > doesn't do a good job creating web sites for end-users. Maybe that was
> > never the goal. Maybe I should just shut up and write the
> > maven-end-user-site plugin? But, it's one reason why I didn't get too
> > exctied about contributing to the site last year. I don't think another
> 100
> > APT documents are the right direction, I think you need to think long
> and
> > hard about the audience, and I think someone other than Hani Sulemani
> needs
> > to say "Maven sites suck" :-) The fact that one of the core
> committers
> > for Maven, had to send out an email entitled "Making the current web
> site
> > suck less", is not a good sell for generating sites with Maven.
> >
> >
> >>>
> >>> On 3/8/06, John Casey <jd...@yahoo.com> 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 look&feel 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 <ws...@gmail.com> wrote:
> >>>>>> On 3/7/06, Brett Porter <br...@apache.org> 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: dev-unsubscribe@maven.apache.org
> >>>>>> For additional commands, e-mail: dev-help@maven.apache.org
> >>>>>>
> >>>>>>
> >>>> ---------------------------------------------------------------------
> >>>> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> >>>> For additional commands, e-mail: dev-help@maven.apache.org
> >>>>
> >>>>
> >> ---------------------------------------------------------------------
> >> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> >> For additional commands, e-mail: dev-help@maven.apache.org
> >>
> >>
> >
>
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.2.5 (MingW32)
>
> iD8DBQFED8RGaCoPKRow/gARAtP4AKCJQwdMKZ9zLx3TtznXjNspY4L2PQCfSqDt
> nRLUZCjKfHinJS/Tog+xJec=
> =xRRx
> -----END PGP SIGNATURE-----
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
>
Re: Making the current web site suck less
Posted by "Brian K. Wallace" <br...@transmorphix.com>.
-----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 <jd...@yahoo.com> 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, I said it. Maven creates so-so web sites for developers, but
> doesn't do a good job creating web sites for end-users. Maybe that was
> never the goal. Maybe I should just shut up and write the
> maven-end-user-site plugin? But, it's one reason why I didn't get too
> exctied about contributing to the site last year. I don't think another 100
> APT documents are the right direction, I think you need to think long and
> hard about the audience, and I think someone other than Hani Sulemani needs
> to say "Maven sites suck" :-) The fact that one of the core committers
> for Maven, had to send out an email entitled "Making the current web site
> suck less", is not a good sell for generating sites with Maven.
>
>
>>>
>>> On 3/8/06, John Casey <jd...@yahoo.com> 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 look&feel 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 <ws...@gmail.com> wrote:
>>>>>> On 3/7/06, Brett Porter <br...@apache.org> 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: dev-unsubscribe@maven.apache.org
>>>>>> For additional commands, e-mail: dev-help@maven.apache.org
>>>>>>
>>>>>>
>>>> ---------------------------------------------------------------------
>>>> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
>>>> For additional commands, e-mail: dev-help@maven.apache.org
>>>>
>>>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
>> For additional commands, e-mail: dev-help@maven.apache.org
>>
>>
>
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.5 (MingW32)
iD8DBQFED8RGaCoPKRow/gARAtP4AKCJQwdMKZ9zLx3TtznXjNspY4L2PQCfSqDt
nRLUZCjKfHinJS/Tog+xJec=
=xRRx
-----END PGP SIGNATURE-----
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Making the current web site suck less
Posted by Brett Porter <br...@apache.org>.
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 <br...@apache.org> 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: dev-unsubscribe@maven.apache.org
>> For additional commands, e-mail: dev-help@maven.apache.org
>>
>>
>
--
Brett Porter <br...@apache.org>
Apache Maven - http://maven.apache.org/
Better Builds with Maven - http://library.mergere.com/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Making the current web site suck less
Posted by Tim O'Brien <to...@discursive.com>.
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 <br...@apache.org> 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: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
>
Re: Making the current web site suck less
Posted by Brett Porter <br...@apache.org>.
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: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Making the current web site suck less
Posted by Brett Porter <br...@apache.org>.
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: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Making the current web site suck less
Posted by Tim O'Brien <to...@discursive.com>.
On 3/9/06, John Casey <jd...@yahoo.com> 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
Posted by John Casey <jd...@yahoo.com>.
Tim O'Brien wrote:
> On 3/8/06, John Casey <jd...@yahoo.com> 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" 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.
If you think that developers don't make good documentation authors, try
having them design the look and feel of a website. I've worked in jobs
where these activities are separated (site design vs.
application/product work..hell, sit design vs. site implementation,
even), and believe me, these things require very different skills. If
you accept that developers don't do well at documenting their products -
though we all agree, they should still do their best - then I don't see
how you can say that we should all be good site designers.
It's important to note here that the site plugin and associated report
plugins don't generate the majority of the content that a site needs.
They don't generate user documentation at all, for instance. They only
translate the formats of the user documentation, if there is any. If you
have concerns about the user's experience and not the developer's, then
discussion about the generated reports would seem a bit lower priority IMO.
>
> 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.
You're not surprising anyone with this. However, note the comment above
about separating site design from report generation.
There, I said it. Maven creates so-so web sites for developers, but
> doesn't do a good job creating web sites for end-users. Maybe that was
> never the goal.
It's not the goal of the reports. Reports are meant to support
developers, which is why they generate javadocs, source
cross-references, team/contributor information, etc. instead of things
that would help a user to use the product.
Maybe I should just shut up and write the
> maven-end-user-site plugin? But, it's one reason why I didn't get too
> exctied about contributing to the site last year. I don't think another 100
> APT documents are the right direction, I think you need to think long and
> hard about the audience, and I think someone other than Hani Sulemani needs
> to say "Maven sites suck" :-) The fact that one of the core committers
> for Maven, had to send out an email entitled "Making the current web site
> suck less", is not a good sell for generating sites with Maven.
>
Again, I think you're confusing document transcoding and report
generation with site design. These are very different activities. I
agree that 10,000,000 APT documents with a HTTPd-generated index page
isn't very useful...just like a bad site design isn't too useful.
However, that's not what the site plugin does. It doesn't design your
site, it only translates the documentation and layout you give it, along
with generating some developer reports.
Look around at Sourceforge sometime, and see how many of the non-Maven
sites out there are well-designed.
Regards,
John
>
>>>
>>> On 3/8/06, John Casey <jd...@yahoo.com> 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 look&feel 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 <ws...@gmail.com> wrote:
>>>>>> On 3/7/06, Brett Porter <br...@apache.org> 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: dev-unsubscribe@maven.apache.org
>>>>>> For additional commands, e-mail: dev-help@maven.apache.org
>>>>>>
>>>>>>
>>>> ---------------------------------------------------------------------
>>>> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
>>>> For additional commands, e-mail: dev-help@maven.apache.org
>>>>
>>>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
>> For additional commands, e-mail: dev-help@maven.apache.org
>>
>>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Making the current web site suck less
Posted by Tim O'Brien <to...@discursive.com>.
On 3/8/06, John Casey <jd...@yahoo.com> 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, I said it. Maven creates so-so web sites for developers, but
doesn't do a good job creating web sites for end-users. Maybe that was
never the goal. Maybe I should just shut up and write the
maven-end-user-site plugin? But, it's one reason why I didn't get too
exctied about contributing to the site last year. I don't think another 100
APT documents are the right direction, I think you need to think long and
hard about the audience, and I think someone other than Hani Sulemani needs
to say "Maven sites suck" :-) The fact that one of the core committers
for Maven, had to send out an email entitled "Making the current web site
suck less", is not a good sell for generating sites with Maven.
> >
> >
> > On 3/8/06, John Casey <jd...@yahoo.com> 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 look&feel 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 <ws...@gmail.com> wrote:
> >>>> On 3/7/06, Brett Porter <br...@apache.org> 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: dev-unsubscribe@maven.apache.org
> >>>> For additional commands, e-mail: dev-help@maven.apache.org
> >>>>
> >>>>
> >> ---------------------------------------------------------------------
> >> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> >> For additional commands, e-mail: dev-help@maven.apache.org
> >>
> >>
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
>
Re: Making the current web site suck less
Posted by John Casey <jd...@yahoo.com>.
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 <jd...@yahoo.com> 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 look&feel 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 <ws...@gmail.com> wrote:
>>>> On 3/7/06, Brett Porter <br...@apache.org> 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: dev-unsubscribe@maven.apache.org
>>>> For additional commands, e-mail: dev-help@maven.apache.org
>>>>
>>>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
>> For additional commands, e-mail: dev-help@maven.apache.org
>>
>>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Making the current web site suck less
Posted by Piéroni Raphaël <ra...@gmail.com>.
2006/3/8, Arnaud HERITIER <ah...@gmail.com>:
>
> 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
Posted by Arnaud HERITIER <ah...@gmail.com>.
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 <to...@discursive.com> 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 <jd...@yahoo.com> 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 look&feel 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 <ws...@gmail.com> wrote:
> > >> On 3/7/06, Brett Porter <br...@apache.org> 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: dev-unsubscribe@maven.apache.org
> > >> For additional commands, e-mail: dev-help@maven.apache.org
> > >>
> > >>
> > >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> > For additional commands, e-mail: dev-help@maven.apache.org
> >
> >
>
>
Re: Making the current web site suck less
Posted by Tim O'Brien <to...@discursive.com>.
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 <jd...@yahoo.com> 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 look&feel 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 <ws...@gmail.com> wrote:
> >> On 3/7/06, Brett Porter <br...@apache.org> 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: dev-unsubscribe@maven.apache.org
> >> For additional commands, e-mail: dev-help@maven.apache.org
> >>
> >>
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
>
Re: Making the current web site suck less
Posted by Tim O'Brien <to...@discursive.com>.
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 <jd...@yahoo.com> 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 look&feel 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 <ws...@gmail.com> wrote:
> >> On 3/7/06, Brett Porter < brett@apache.org> 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: dev-unsubscribe@maven.apache.org
> >> For additional commands, e-mail: dev-help@maven.apache.org
> >>
> >>
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
>
Re: Making the current web site suck less
Posted by John Casey <jd...@yahoo.com>.
+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 look&feel 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 <ws...@gmail.com> wrote:
>> On 3/7/06, Brett Porter <br...@apache.org> 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: dev-unsubscribe@maven.apache.org
>> For additional commands, e-mail: dev-help@maven.apache.org
>>
>>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Making the current web site suck less
Posted by Tim O'Brien <to...@discursive.com>.
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 <ca...@apache.org> 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=382904&view=markup
>
> We're missing the continuous integration part to auto deploy site
> everytime it's changed
>
> On 3/8/06, Tim O'Brien <to...@discursive.com> 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 <ws...@gmail.com> wrote:
> > >
> > > On 3/7/06, Brett Porter <br...@apache.org> 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: dev-unsubscribe@maven.apache.org
> > > For additional commands, e-mail: dev-help@maven.apache.org
> > >
> > >
> >
> >
>
>
> --
> I could give you my word as a Spaniard.
> No good. I've known too many Spaniards.
> -- The Princess Bride
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
>
Re: Making the current web site suck less
Posted by Carlos Sanchez <ca...@apache.org>.
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=382904&view=markup
We're missing the continuous integration part to auto deploy site
everytime it's changed
On 3/8/06, Tim O'Brien <to...@discursive.com> 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 <ws...@gmail.com> wrote:
> >
> > On 3/7/06, Brett Porter <br...@apache.org> 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: dev-unsubscribe@maven.apache.org
> > For additional commands, e-mail: dev-help@maven.apache.org
> >
> >
>
>
--
I could give you my word as a Spaniard.
No good. I've known too many Spaniards.
-- The Princess Bride
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Making the current web site suck less
Posted by Brett Porter <br...@apache.org>.
Please review:
http://mail-archives.apache.org/mod_mbox/maven-dev/200602.mbox/%3C43E97D27.8080900@apache.org%3E
And provide feedback.
Closely related to:
http://mail-archives.apache.org/mod_mbox/maven-dev/200602.mbox/%3C43E96733.5070309@apache.org%3E
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 <ws...@gmail.com> wrote:
>> On 3/7/06, Brett Porter <br...@apache.org> 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: dev-unsubscribe@maven.apache.org
>> For additional commands, e-mail: dev-help@maven.apache.org
>>
>>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Making the current web site suck less
Posted by Brett Porter <br...@apache.org>.
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 <ws...@gmail.com> wrote:
>> On 3/7/06, Brett Porter <br...@apache.org> 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: dev-unsubscribe@maven.apache.org
>> For additional commands, e-mail: dev-help@maven.apache.org
>>
>>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Making the current web site suck less
Posted by Lukas Theussl <lt...@apache.org>.
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: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Making the current web site suck less
Posted by Tim O'Brien <to...@discursive.com>.
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 <ws...@gmail.com> wrote:
>
> On 3/7/06, Brett Porter <br...@apache.org> 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: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
>
Re: Making the current web site suck less
Posted by Milos Kleint <mk...@gmail.com>.
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 <ra...@gmail.com> 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 <br...@apache.org> 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: dev-unsubscribe@maven.apache.org
> > For additional commands, e-mail: dev-help@maven.apache.org
> >
> >
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Making the current web site suck less
Posted by Carlos Sanchez <ca...@apache.org>.
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 <ra...@gmail.com> 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 <br...@apache.org> 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: dev-unsubscribe@maven.apache.org
> > For additional commands, e-mail: dev-help@maven.apache.org
> >
> >
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
>
--
I could give you my word as a Spaniard.
No good. I've known too many Spaniards.
-- The Princess Bride
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Making the current web site suck less
Posted by Rinku <ra...@gmail.com>.
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 <br...@apache.org> 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: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Making the current web site suck less
Posted by "Brian K. Wallace" <br...@transmorphix.com>.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Wendy Smoak wrote:
> On 3/7/06, Brian K. Wallace <br...@transmorphix.com> 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: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Making the current web site suck less
Posted by Wendy Smoak <ws...@gmail.com>.
On 3/7/06, Brian K. Wallace <br...@transmorphix.com> 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: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Making the current web site suck less
Posted by "Brian K. Wallace" <br...@transmorphix.com>.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Wendy Smoak wrote:
> On 3/7/06, Brett Porter <br...@apache.org> 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: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Making the current web site suck less
Posted by Wendy Smoak <ws...@gmail.com>.
On 3/7/06, Brett Porter <br...@apache.org> 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: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org