We should have (a possibly categorised) index.
On 19/06/2006 10:30 PM, Jeff Jensen wrote:
Contrarian, one thing that is useful about the current approach is the
browser search feature. It works pretty well to find the topics on a doc
page with lots of entries and common search words. Hopefully the reorg
solution doesn't lose a search-ability/adds a better search.
-----Original Message-----
From: Jason van Zyl [mailto:[EMAIL PROTECTED]
Sent: Monday, June 19, 2006 7:21 AM
To: Maven Developers List
Subject: Re: [Proposal] Documenting Maven
On 19 Jun 06, at 8:08 AM 19 Jun 06, Geoffrey De Smet wrote:
Humans aren't capable to read more then 9 entries.
Many of the questions asked on the user list are actually in the
guides.
So why don't they find it?
http://maven.apache.org/guides/index.html
links to a lot of good guides, but the way it is structured is plain
wrong imho:
- When people want to learn something about for example site
deployment and they get the choice from "Mini Guides", "Introductory
Material", "Reference", ... they don't know what to choose.
- When the pick "Mini Guides" they have to read 20+ entries, so 11+ to
many.
Yup, I think everyone agrees. I just tried to jam as much content in there
in as short a period of time as I could. A simple categorization/trail
mechanism would be better.
How would it look to you ideally? Would you categorize those and place the
categories on the front page? Point to a documentation page with the
categories listed there? I think these are really the questions we would
like answers to. Guidance from users for our user documentation which will
be the bulk of our documentation. Would you be willing to make a quick
sample of what you think would work best?
Jason.
A refactor of that page, into a tree based structured on the
functionality (not the format) will help a lot.
The format (mini guide or introdcutory material) can be mentioned next
to the entry.
Brett Porter wrote:
John Casey wrote:
Hi everyone,
I know we've talked about this quite a bit already. Actually, I'm
having trouble finding the past threads on this topic in my
email...can someone who knows please link them in?
btw:
http://mail-archives.apache.org/mod_mbox/maven-dev/200603.mbox/%
[EMAIL PROTECTED] http://mail-archives.apache.org/
mod_mbox/maven-dev/200603.mbox/[EMAIL PROTECTED]
However, I'm reading through them and going to reincoporate any
additional thoughts into the current discussions (as I should have
done *ages* ago).
- Brett
--
With kind regards,
Geoffrey De Smet
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED] For
additional commands, e-mail: [EMAIL PROTECTED]
Jason van Zyl
[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]
--
Brett Porter <[EMAIL PROTECTED]>
Apache Maven - http://maven.apache.org/
Better Builds with Maven - http://library.mergere.com/
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
