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]
