You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@maven.apache.org by "John Casey (JIRA)" <ji...@codehaus.org> on 2006/01/19 20:55:36 UTC
[jira] Updated: (MNG-1987) Set a minimal standard for plug-in
documentation
[ http://jira.codehaus.org/browse/MNG-1987?page=all ]
John Casey updated MNG-1987:
----------------------------
Fix Version: documentation
> 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
> Fix For: documentation
>
>
> 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: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org