[ http://jira.codehaus.org/browse/MNG-1987?page=all ]
Marvin King updated MNG-1987:
-----------------------------
Attachment: (was: MNG-1987-maven-site[partial].patch)
> 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
> Assignee: Marvin King
> Fix For: 2.0.5
>
> Time Spent: 17 hours
> Remaining: 0 minutes
>
> 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
