On 26 May 07, at 1:47 AM 26 May 07, Henri Yandell wrote:
Will do - not that I have much thought-wise yet. I also think the
current website and structure is not terrible; so to solve the
complaints we need to understand why people are complaining.
Some more thoughts....
.... Go to maven.apache.org. Minor irritation - the visited links are
the same colour as the text.
... Good first paragraph. Describes the product, teaches POM acronym
immediately. Succint.
There is a lot of content in the introductory presentations that
could be moved to the site if you wanted more material for people new
to Maven. Maven the Beautiful City probably has everything we want to
tell new users about Maven.
Just a thought.
... Wording on next paragraph is bad. "If you think". A newcomer who
is asking 'What is Maven' is not thinking that it can help, they're
just thinking wtf is this thing I've been hearing about. Good content
here though, though the FAQ is bad. It doesn't contain what this says
it contains.
Again we can extract from presentations and good introductory content.
ITEM: Kill this FAQ. Remove navlink and move FAQ entries to a wiki
FAQ. [Warning: I believe wikis are good for drafting documentation and
managing wikis, rather than hosting official documentation :) Plus
wiki's need editors. ]
+1
... Next section on front page is basically the documentation home
page. I like that there is a 'Run Maven' section, that's good. My
temptation is to move this to its own page, include a small number of
subsections under each of the 5, but have many more subsections for
the user-centric ones than the committer-centric.
+1
... Documentation index section could wrap into the documentation
page. It seems rather unuseful though. I've clicked on it before and
immediately clicked off.
+1
... Plugins list. Good I guess. I mean I asked for such a thing in my
reply to Brett; though I was thinking more of a wiki one where all the
3rd party plugins were listed too
(http://docs.codehaus.org/display/MAVENUSER/MavenPlugins I guess).
It all needs to be combined but as you've suggested I think official
plugin documentation should be on the site. Satellite projects like
Mojo should have the same plugin page structure and we could link to
it. We can ask any 3rd party groups providing Maven plugins to follow
the structure we've come up with here.
... Random thought. I wonder if the repository should be a separate
subproject of Maven. ie) own mailing list, and the various bits of
repository information that are on the website could be collated into
a single small set of pages. Seems that every now and then I come
across a snippet relating to that.
Probably couldn't hurt and we were going to setup a mailing list here
for it anyway as all resources are being shut down on the current
central machine and the new machine is going to be purely dedicated
to serving the repository.
... Subprojects get shortchanged on the website. Hidden away in the
bottom left. I'd be tempted to use the space saved by a documentation
page to have a table showing the subprojects that explains what they
are (yeah I know, like on the bottom of jakarta.apache.org where no
one looks... I'm reverting to comfort).
+1
... Maven Ant tasks documentation doesn't seem to be a part of the
other documentation blobs; just a link on the right.
+1
... Sonatype book not on the 3rd party resources yet.
+1
... Could also treat Maven Plugins as a subproject [at least website
wise; not implying independent mailing lists etc when I say this].
Anything to simplify the navbars really.
I think just putting them all together for now would be a good thing.
You mean as in sub-project where we collect all Maven related plugins
apache-wide?
... Powered by link is useless in my opinion. Make this a bit of blurb
on the About Maven other pages; maybe at the bottom of Features. It's
impossible to keep up with the list (which is great as it shows
success), so just make it blurb that says "Did you know Maven2 powers
these projects?". Let's update it to have better names.
I think people like the powered by page as it gives an indication of
real projects using Maven. I think it helps people decide whether or
not to use Maven. It's probably woefully out of date though.
... Personally I'd like to see Ivy mentioned somewhere. Maybe on an
expanded Maven Ant Tasks page.
Sure, it's definitely a big user of our technology and is a path to
doing artifact driven development.
... There's no IDEA integration for Maven? Given the shortness of
these pages; I would merge into a single page on IDE Integration and
drop the navbar menu. Include the latest on IDEA. Possibly put under
the About Maven section.
There is now. Well, as of yesterday in fact.
... Drop the Maven 1 information from the 3rd party section. That can
live on the Maven 1.x pages. External Resource pages always seem to be
a good idea for wikis, it lets the authors add them rather than
committers.
+1
... ApacheCon banner looks crap. Looks like there's space for two ads
there but only one showing.
Okay... sorry that was more website than documentation focused. Helped
me get a good feel for the site and hopefully had some value.
That's cool, I say try it before the thrill peters out :-)
Hen
On 5/25/07, Jason van Zyl <[EMAIL PROTECTED]> wrote:
Hen,
How about doing mockups in the wiki? Of the actual layout, then
people can tool around and you can flesh out what you're thinking.
On 25 May 07, at 2:02 PM 25 May 07, 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]
>
>
Thanks,
Jason
----------------------------------------------------------
Jason van Zyl
Founder and PMC Chair, Apache Maven
jason at sonatype dot com
----------------------------------------------------------
---------------------------------------------------------------------
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]
Thanks,
Jason
----------------------------------------------------------
Jason van Zyl
Founder and PMC Chair, Apache Maven
jason at sonatype dot com
----------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
