Improve documentation on using archetypes
-----------------------------------------
Key: JBEHAVE-574
URL: https://jira.codehaus.org/browse/JBEHAVE-574
Project: JBehave
Issue Type: Task
Reporter: Mauro Talevi
Assignee: Mauro Talevi
Fix For: 3.5
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"
--
This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira
---------------------------------------------------------------------
To unsubscribe from this list, please visit:
http://xircles.codehaus.org/manage_email
