[jira] Commented: (MCLOVER-47) review plugin documentation
[ http://jira.codehaus.org/browse/MCLOVER-47?page=comments#action_74386 ] Vincent Massol commented on MCLOVER-47: --- Hi Franz, Thanks! I've not applied your patch yet because I'm still unsure about the "Examples" section: * I think I preferred the "Usage" version I had before (it was named "How to Use" before). You have modified the section headers to reflect the goals but I think it's better to make it a usage document rather than a goal documentation. Usage is more broad than goal reference doc as what users are interested in is to perform some tasks and we tell them how to chain the different goals and configuration to achieve this. I prefer it to be "use case" oriented rather than "goal"-oriented. * I'd like that all the "examples" you've separated be put back in the "Usage" section. This goes together with my first point. I still don't see anything that we would have to put in the Examples section right now so I'd like it empty. I don't mind if it raises a docck warning. I'd argue that it's docck which is faulty... ;-) (or maybe I don"t understand the split between usage and examples). We should raise this on the dev list but I will not lower the quality of the doc to avoid a docck warning ;-) If "Examples" were named "Usages" I wouldn't have any issue with it. I've just committed some small changes for now. We still need to find a solution for the Examples section... What I think will be nice is to have a TOC in the usage document. I'll try to find out if it's possible with APT. Thanks > review plugin documentation > --- > > Key: MCLOVER-47 > URL: http://jira.codehaus.org/browse/MCLOVER-47 > Project: Maven 2.x Clover Plugin > Issue Type: Task >Affects Versions: 2.2 >Reporter: John Tolentino > Assigned To: Vincent Massol > Fix For: 2.3 > > Attachments: MCLOVER-47-maven-clover-plugin-2.patch, > MCLOVER-47-maven-clover-plugin.patch > > > http://docs.codehaus.org/display/MAVEN/Maven+Plugin+Documentation -- 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
[jira] Commented: (MCLOVER-47) review plugin documentation
[ http://jira.codehaus.org/browse/MCLOVER-47?page=comments#action_74158 ] Franz Allan Valencia See commented on MCLOVER-47: - Good day to you, Vincent, Regarding the "Examples Section": Based from my understanding of the docck plugin and from the previous revised plugin docus before mine, I believe that the Usage Section is used to contain the basic uses cases, usually, one each goal. While the details of these use cases such as the optional and not so common/basic configurations are placed in the Examples Section. In this way, the users may read the Usage section to get a good idea of how to use it in their project, and they can use the Examples section as a quick reference for some configurations that they may need. At least this is to my understading. WDYT? :-) Regarding the Authorship and the Titles of the Documentation: Sorry about that :-) I failed to edit my copy-pastes :-) Thanks, Franz > review plugin documentation > --- > > Key: MCLOVER-47 > URL: http://jira.codehaus.org/browse/MCLOVER-47 > Project: Maven 2.x Clover Plugin > Issue Type: Task >Affects Versions: 2.2 >Reporter: John Tolentino > Assigned To: Vincent Massol > Fix For: 2.3 > > Attachments: MCLOVER-47-maven-clover-plugin.patch > > > http://docs.codehaus.org/display/MAVEN/Maven+Plugin+Documentation -- 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
[jira] Commented: (MCLOVER-47) review plugin documentation
[ http://jira.codehaus.org/browse/MCLOVER-47?page=comments#action_74023 ] Vincent Massol commented on MCLOVER-47: --- Hi Franz. Thanks for your patch. Good work! I've started to apply it. The only part that seems strange is the examples section. What you have moved to there from my howto guide are NOT examples but usage documentation! Examples are scattered throughout the usage section and I don't understand why there's a need to have a specific examples section. I know docck seems to require it but I'd like to better understand the need for this section before applying anything. Also, please add my name to all documents containing text that you have reused from my howto guide :-) And make sure to change their titles as "Simple" doesn't seem right ;-) Let me know what you think. Thanks -Vincent > review plugin documentation > --- > > Key: MCLOVER-47 > URL: http://jira.codehaus.org/browse/MCLOVER-47 > Project: Maven 2.x Clover Plugin > Issue Type: Task >Affects Versions: 2.2 >Reporter: John Tolentino > Assigned To: Vincent Massol > Fix For: 2.3 > > Attachments: MCLOVER-47-maven-clover-plugin.patch > > > http://docs.codehaus.org/display/MAVEN/Maven+Plugin+Documentation -- 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
