On 19 Jun 06, at 8:56 AM 19 Jun 06, Brett Porter wrote:
Pretty hesitant to modify APT since we got it from another source
(afraid I already violated that with || for table headers).
Oh, it was maimed the second it arrive here :-)
Is there a standard way we can add extra markup? Is it something
that is also possible in other input formats? (I guess <properties
in xdoc, <meta in xhtml?)
In APT the only option would be a comment. The format has been
tampered with so I don't see any harm in extending it further.
But yes, I think that's a good idea. I don't have the issue to
hand, but it's under the MNG documentation category already if you
wanted to add this as a possible solution.
Cheers,
Brett
On 19/06/2006 10:49 PM, Jason van Zyl wrote:
On 19 Jun 06, at 8:39 AM 19 Jun 06, Brett Porter wrote:
We should have (a possibly categorised) index.
What if we slightly altered the the APT parser to pick up a tags/
categories identifier? We could even just put it in the title line
so we could start categorizing today. Something like:
-----
Site Management {site,navigation}
-----
Date
-----
Author
Then we can start the process and alter the parser later.
Just a thought.
Jason.
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]
Jason van Zyl
[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]
Jason van Zyl
[EMAIL PROTECTED]
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
