Tim O'Brien wrote:
On 3/8/06, John Casey <[EMAIL PROTECTED]> wrote:
<snip>
Something to think about is maybe not having the initial Maven page be a
Maven site. ASF sites in general seems to be more Developer focused
than
user focused. What if the initial Maven site were more like the front
pages
of Mozilla or Rails. An attractive logo, links to resources and
materials,
an introduction. The home page should be user focused, Maven developers
are
a minority of the audience here.
Are you saying that the developer-centric tendency is appropriate for
ASF project web sites, then? I'd tend to say that for a product like
Maven (not an API, like commons-cli, for instance) it's worth striving
to help the user. Since Maven is an Apache product/project, I'd say that
having a developer site on a different physical location would be
bad...they're different aspects of the same product/project. That said,
I think we need to section the developer docs off and put them a click
or so in from the main landing page...probably with their own landing
page.
I think I agree with you.
When I said "developer-centric" I meant
"apache-developer-centric". IMO, more projects need to think about the user
who has "30 seconds to figure out the best way to download/use Derby". The
current Maven site has too many links, too much distracting people from what
should be a simple message - "Download Maven, you won't believe how you
developed without it. We promise.". I'm not saying that we should all
become marketing people, but it's something to consider.
I agree with you on that point. My point was that physical separation of
the websites might not be appropriate or necessary, since IMO every ASF
project that releases a product (not an API) should apply this advice,
and therefore should have a user-driven aspect, behind which lurks a
developer-driven section, one click away. The developer pages don't have
to invade the landing page, but there should be a link (to elsewhere on
the same physical web site).
It's not a simple hierarchy, but then, we have a great deal of variation
among our audience members. As these audience members [possibly]
transition from users to contributors and so on, we don't want a
separation like this to get in their way...there should be *some*
cohesiveness, I would think...
I'm not saying this to be contrary, bear with me: most people that use
Maven don't care to know much about the internals or how it is being
developed. They simply want to download a product that works, is
well documented, and use it. A small minority of those users will get an
itch that needs to be scratched or decide that the gift of free software
should be repaid by involvement in a community. So, if you wrote up a
survey, and quizzed people who use Maven every day, I think you'd probably
find that most of them think Jason van Zyl is a famous magician and the
Meritocracy is a spell in Dungeons and Dragons. I'm not saying this as a
cynical jibe, but to make the point that regardless of the Maven website, we
will always about an equal mix - out of 100 - 95 people download Maven, 5
subscribe to the users list for a week, maybe 4 ask questions on the user
list, and, if you are lucky, 1 submits a patch. And even that's
overestimating, apply that forumla to the httpd project and it would have
10^5 patches submitted per year.
Turn your statement around. "....audience members [possibly] transition
form users to contributors". Assume that a simpler user focused launch
page made it easier for people to adopt Maven. If this "separation" of
user-focused and developer-focused documentation increases the population of
users, we've increase the pool of potential contributors. I'm betting on
the fact that as users "root around" the documentation, they'll catch on to
the fact that this is the ASF they will pick up the community.
I think a good strategy is to make the landing page for Maven as simple as
possible, with a good short sell, as little text as possible, link to
download, and some news and announcements. The Maven launch page should be
very similar to the Mozilla launch page - there are still links to the
developer pages.
See my comments above. Again, this isn't about merging the developer and
user communities, forcing them to read the same webpages and filter the
content that pertains to them. It's about whether we want to move toward
uniting all of the Maven project content to make it look like part of
the same site, albeit in different sections. I can't think of very many
people who might disagree that our site needs some organizational help,
and a heavy-ish touch of user-friendliness.
Instead we've got a link named "Netbeans Module", a link on the top of the
page to "Maven" followed by a link to "Maven 2.x" and "Maven 1.x". All the
links have a 20% change of having a completely different skin. There are
links to a Wiki and external sites that are not labeled as such. There is a
"Project Team" report (http://maven.apache.org/team-list.html) that doesn't
list have of the people involved in Maven. Did you know there are no
contributors to the Maven project and that there are only 8 people working
on Maven"? For some reason, I know what the "Actual Time" is for all the
people on the project team down to the second (I've never figured the need
for that field out), but good luck customizing the team-list support. :-)
Here's another good one, click on a Guide, then click on the banner logo.
That links back to /guide, click on the same banner logo, that links back to
the home page. The Maven site is full of these inconsistencies, and it's
not something that people can just fix with patches. IMO, the site plugin
needs serious rework. It doesn't create good web sites, especially
for multi-projects.
If you think that developers don't make good documentation authors, try
having them design the look and feel of a website. I've worked in jobs
where these activities are separated (site design vs.
application/product work..hell, sit design vs. site implementation,
even), and believe me, these things require very different skills. If
you accept that developers don't do well at documenting their products -
though we all agree, they should still do their best - then I don't see
how you can say that we should all be good site designers.
It's important to note here that the site plugin and associated report
plugins don't generate the majority of the content that a site needs.
They don't generate user documentation at all, for instance. They only
translate the formats of the user documentation, if there is any. If you
have concerns about the user's experience and not the developer's, then
discussion about the generated reports would seem a bit lower priority IMO.
I guess I've just pissed off the Maven development team by telling all of
you that Maven doesn't do a good job of creating web sites for
users.
You're not surprising anyone with this. However, note the comment above
about separating site design from report generation.
There, I said it. Maven creates so-so web sites for developers, but
doesn't do a good job creating web sites for end-users. Maybe that was
never the goal.
It's not the goal of the reports. Reports are meant to support
developers, which is why they generate javadocs, source
cross-references, team/contributor information, etc. instead of things
that would help a user to use the product.
Maybe I should just shut up and write the
maven-end-user-site plugin? But, it's one reason why I didn't get too
exctied about contributing to the site last year. I don't think another 100
APT documents are the right direction, I think you need to think long and
hard about the audience, and I think someone other than Hani Sulemani needs
to say "Maven sites suck" :-) The fact that one of the core committers
for Maven, had to send out an email entitled "Making the current web site
suck less", is not a good sell for generating sites with Maven.
Again, I think you're confusing document transcoding and report
generation with site design. These are very different activities. I
agree that 10,000,000 APT documents with a HTTPd-generated index page
isn't very useful...just like a bad site design isn't too useful.
However, that's not what the site plugin does. It doesn't design your
site, it only translates the documentation and layout you give it, along
with generating some developer reports.
Look around at Sourceforge sometime, and see how many of the non-Maven
sites out there are well-designed.
Regards,
John
On 3/8/06, John Casey <[EMAIL PROTECTED]> wrote:
+1
Maybe we can put a banner at the top of each page that marks the
version
it refers to or something. If we styled the reference doco as a manual,
it could be part of the page layout that ties it together. I'd be
willing to trade a bit of the look&feel for that sort of information,
as
it seems to me that it would reduce confusion.
-john
Tim O'Brien wrote:
Having to choose between publishing the latest and greatest docs and
only
the released version is a problem that Maven seems to have created for
itself. Same issue comes up in other projects frequently - Commons
has
a
problem because some of the sites only publish on a release. Latest
and
greatest are almost never there.
What about publishing the latest and greatest docs to another
directory?
The Maven site gets pushed to a directory that has a version of a
label. http://maven.apache.org/version/1.0
, http://maven.apache.org/version/2.0.2, and
http://maven.apache.org/version/trunk. This way the Maven site can
have
a
nightly publish of the most current Maven site to Trunk every single
day,
but still keep legacy docs around intact for people using older
versions
of
the product. The "consumer" site can point to the latest release, and
the
"developer" site can point to "trunk". The Maven site plugin would
need
some mechanism for adding a skin to a site to clearly identify it as
"Development".
On 3/7/06, Wendy Smoak <[EMAIL PROTECTED]> wrote:
On 3/7/06, Brett Porter <[EMAIL PROTECTED]> wrote:
* I'm still a little torn on where plugin docs go. No hurry on this,
but
something to ponder. We definitely need to make the references for
those
integrate better. Site/skin inheritance will help
No matter where they go, I think they need to be updated more often.
Random example... the assembly plugin docs are wrong, and have been
that way for months. (it's descriptorId, not
maven.assembly.descriptorId.)
* http://maven.apache.org/plugins/maven-assembly-plugin/howto.html
I would like to see the "latest and greatest" docs on the main site.
Yes, they'll be ahead of the released version, but not by much, and
(hopefully) not for long.When the answer to a lot of "X doesn't work"
questions is "It's fixed in the trunk, use a snapshot," it would be
nice to have the snapshot docs available in a centralized place.
This also makes it more fun to contribute to the documentation,
because you get to see your work "in print" right away.
Thanks for updating the main site. :)
--
Wendy
---------------------------------------------------------------------
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]
