Probably; maybe; I think I'm still playing catchup on understanding the problem :)
On 5/25/07, Brett Porter <[EMAIL PROTECTED]> wrote:
Agreed. Here is how I imagine this being laid out: - each specific example would be in a plugin that it related to, making it possible to go to a plugin as a "reference" page if you already know what you are doing and are looking to cut-and-paste something in. eg. http://maven.apache.org/plugins/maven-surefire- plugin/examples/inclusion-exclusion.html - things that span multiple plugins would go into the cookbooks (wiki content) on the main site under the relevant section (perhaps linking to relevant plugins) - both sets of examples are pulled together in howto guides from the main documentation (some such howto guides would be the m1 -> m2 one, or the ant -> m2 one) - all examples are also pulled in to the categories index pages (I think this is what's related to what Jason is doing). Does that seem consistent? - Brett On 26/05/2007, at 3:10 PM, Henri Yandell wrote: > I think so. > > The separation of authoring is good - but there needs to be a good > "How do I do Xxx?" -> plugin lookup; and a good central FAQ for the > plugins. > > ie) "How do I add java.awt.headless to my tests?" > > That can then link over to the surefire page on system properties. > > So categorise a big FAQ on user-centric feature and not development > plugins; and then do lots of linking to pages rather than answering of > questions. > > That can live very naturally on the wiki I think. If I'm a natural > example of a user, a lot of the time my question is "How do I ..." and > eventually it turns out it was documented on a plugin page quite > happily, I just had to go to #maven to get all the pieces to the > puzzle. Usually name of plugin and the name the plugin gives said > feature. > > I imagine most users to m2 are new, so m1->m2 stuff is much less > useful. Though when googling today I found lots of things telling me > the m1 property to add to project.properties to set headless mode for > junit. So the actual question I came to maven.apache.org with was "How > do I do this m1 thing in m2?". > > Hen > > On 5/25/07, Brett Porter <[EMAIL PROTECTED]> wrote: >> +1 on both. Important thing for "plugin documentation needs to be >> folded into main documentation" though - I assume you mean this in a >> logical way (ie, strong contextual links from the documentation to >> the plugin documentation), and not a physical way? >> >> - Brett >> >> On 26/05/2007, at 4:02 AM, Henri Yandell wrote: >> >> > I didn't notice any threads on the doc organization topic, so >> thought >> > I'd start one. Apologies if I missed the right place, [EMAIL PROTECTED] >> is the >> > noisiest list I'm on. >> > >> > Compare and contrast: >> > >> > http://maven.apache.org/guides/ >> > >> > and >> > >> > http://httpd.apache.org/docs/2.2/ >> > >> > --- >> > >> > Firstly, there is no real Maven documentation home page. It's a >> part >> > of the front page, which clashes with the sheer amount of space >> that >> > news, announcement and other things need. So suggested step 1: >> We need >> > a documentation page. >> > >> > Secondly, it's obvious that much of the httpd page concerns >> mod_foos >> > that are included by default. With Maven, these plugin >> documentation >> > pages are _much_ harder to find. They're not even listed under >> > documentation but involve you having to know that you want to use a >> > plugin and then go look at its docs. So suggested step 2: Plugin >> > documentation needs to be folded into main documentation. >> > >> > Will add more as I go; I need to dig through the wiki sprawl to >> > understand how this is being solved; I'm sure the above isn't news. >> > >> > Hen >> > >> > >> --------------------------------------------------------------------- >> > To unsubscribe, e-mail: [EMAIL PROTECTED] >> > For additional commands, e-mail: [EMAIL PROTECTED] >> >> --------------------------------------------------------------------- >> To unsubscribe, e-mail: [EMAIL PROTECTED] >> For additional commands, e-mail: [EMAIL PROTECTED] >> >> > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [EMAIL PROTECTED] > For additional commands, e-mail: [EMAIL PROTECTED] --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
