Set a minimal standard for plug-in documentation
------------------------------------------------
Key: MNG-1987
URL: http://jira.codehaus.org/browse/MNG-1987
Project: Maven 2
Type: Wish
Components: documentation - general
Reporter: Bengt-Erik Fröberg
There are many repositories and providers of Maven2 plugins.
However, layout and,above all, content vary in lenghth and information value.
A few providers had made efforts to document, and others tend to completely
skip this step
as if one could guess how to configure or use the plugin in the best way.
I had a very positive and inspiring experience with the
http://cargo.codehaus.org/Maven2+plugin plugin documentation, and from a
pedagogical and user-oriented point of view this makes the difference between
"yes" and "no way".
Compare this to the sparse deploy:deploy plugin docs.....
I will try to pinpoint the reasons my immediate love with this documentation
style:
1) From very basic to advanced (minimal, small-intermediate and full-fledged
configuration) - pedagogical
2) Listing of different use-cases with appropriate descriptions. Note the
progressive approach - no guessing games needed and very pedagogical.
3) Examples, examples and examples - show us how it's done, and we get happy!!!
It does not matter that there are some "TODO"s in the page, you just love the
guys that wrote it.
I really would like a minimal set of criteria being fulfilled in terms of
documentation: At least three levels of config,
some common and some special use cases and a lot of example code.
In some other plugin docs there are examples, that's true, but I don't think
they interact very well with the written text.
One example is http://maven.apache.org/plugins/maven-antrun-plugin/usage.html
(at least this plugin has a "usage" section.
Slightly uninformative text aside the examples, and some references to things
you obviously should know...
I hope this could lead to a discussion about docs in general, but plugin ones
especially.
Regards,
/B-E Fröberg
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://jira.codehaus.org/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
