Improve documentation on using archetypes

Based on feedback from Taylor Gautier:

"Hi,

Would someone be able to identify the actual steps/syntax required to execute a maven archetype to create a project?

I can't seem to get it to work.

The documentation here: http://jbehave.org/reference/stable/archetypes.html doesn't seem sufficient for a new user to figure out how to make it work - I dug around and could not find this archetype catalog file (and why is it necessary? This is the first time I've encountered such a thing).

According to the docs this file is in the "binary" distribution - but what exactly is that? In the "downloads" section of the website the links all point to maven repositories, as such there does not seem to be a canonical "binary" distribution, so it's very unclear - to me at least - which file would actually contain this archetype catalog - and I did look around in some of the jar files – for example in the spring archetype jar file the following are the only xml files that exist:

• archetype-resources/pom.xml
• archetype-resources/src/main/resources/my_steps.xml
• META-INF/maven/archetype-metadata.xml

none of which - you will note - is actually called archetype-catalog.xml. Also, in jbehave core, the following are the only xml files:

• META-INF/maven/org.jbehave/jbehave-core/pom.xml

Other info that is missing: the archetype group id (it's org.jbehave).

Rather than forcing users to figure everything out on their own by writing "you need to specify the usual GAV coordinates" I would humbly suggest that maven archetypes are intended for beginners (by definition, not likely to be maven experts, not to mention that the word GAV is not a recognized term of art in the maven world) and therefore better documentation, with actual working examples, would go a long way towards creating a friendly user experience.

For a good example of user documentation with proper working examples, please refer to the camel website: http://camel.apache.org/camel-maven-archetypes.html

Thanks,

Taylor"