You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by Jon Stevens <jo...@latchkey.com> on 2001/07/03 03:29:41 UTC
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS:
[TomcatDocu mentation Redactors To Hire]
on 7/2/01 6:04 PM, "Christopher Cain" <cc...@mhsoftware.com> wrote:
> I
> have no interest in Anakia, and quite frankly, as has been pointed out
> very astutely by Costin, I have no interest in bothering with XML for
> the purposes of documentation. I will produce HTML docs with my favorite
> editor and call it a task adequately completed. Asking anything beyond
> that will more than likely be more time and effort than I am prepared to
> invest in simple documentation.
I bet you will only use a certain brand of toilet paper as well.
> In short, let us please continue and decide upon how to proceed.
> Regardless of Jon's off-topic confusion, I would really like to know how
> the community would like to see any documentation which I may
> contribute.
>
> - Christopher
That's good, cause I haven't seen you contribute anything so far, Ace.
The answer is simple...
<?xml version="1.0"?>
<document>
<properties>
<author email="ccain@mhsoftware.com">Christopher Cain</author>
<title>Cain's Documentation</title>
</properties>
<body>
<section name="Recent News">
<p>
Mr. Cain actually writes a bit of documentation instead of threatening us
with the idea that he might do it someday if we are lucky.
</p>
</section>
</body>
</document>
:-)
-jon
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project
:WAS:[TomcatDocumentation Redactors To Hire]
Posted by "Geir Magnusson Jr." <ge...@optonline.net>.
Christopher Cain wrote:
>
> Anyway, since it sounds like Geir has graciously volunteered to help me
> form the "Ministry of Documentation" as he so cleverly coined it, the
> point is more or less moot now. Users can submit plain text if they
> like, and I certainly have no problems learning whatever the community
> decides upon. Everybody wins.
Let me clarify - that was a typo. What I typed read :
"I would be someone might volunteer to be Minister of Documentation..."
and what I was missing was a 't', for it to read
"I would bet someone might volunteer to be Minister of Documentation..."
meaning that Tomcat has a *huge* community of users and developers, and
someone who is a user of Tomcat and talented at writing might offer to
help out like that. As long as the community recognizes that its an
important role, all will be well, especially if you can find someone to
take the lead and assert direction and guidance to the project.
I am willing to help of course as a satisfied Tomcat user, but I cannot
be the Minister. I am too swamped by OSS and professional commitments.
geir
--
Geir Magnusson Jr. geirm@optonline.net
System and Software Consulting
Developing for the web? See http://jakarta.apache.org/velocity/
You have a genius for suggesting things I've come a cropper with!
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project
:WAS:[TomcatDocu mentation Redactors To Hire]
Posted by Jon Stevens <jo...@latchkey.com>.
on 7/3/01 4:00 PM, "Christopher Cain" <cc...@mhsoftware.com> wrote:
> Anyway, I had no idea that Anakia was your product. I will most
> certainly have a look and provide my official critique. Since your
> stance on JSP is dead-on accurate, and I hear that your replacement tool
> is actually something of an improvement, Anakia certainly deserves a
> look.
>
> - Christopher
I want Anakia to stand on its own instead of being "my product" so I don't
hold that out as a carrot for people to munch on.
In reality, what you need to use is the jakarta-site2 module which is an
application built around Anakia. Ie: it is a pre-fabricated .vsl file,
examples and build scripts that allow you to quickly get started creating
documentation. You can also look at the jakarta-tomcat-site module which is
already setup to have the dependency on jakarta-site2.
Like I said before, everything you need to write documentation is already
there...discussing this over and over again is futile.
-jon
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project :WAS:[TomcatDocu
mentation Redactors To Hire]
Posted by Christopher Cain <cc...@mhsoftware.com>.
Jon Stevens wrote:
>
> on 7/3/01 11:50 AM, "Christopher Cain" <cc...@mhsoftware.com> wrote:
>
> > The more (most) people have to
> > try and learn an extensive DTD or templating system, the less likely
> > they are to bother.
>
> I agree. That is why I came up with Anakia. It is brain dead simple to use
> and runs extremely quickly. The "DTD" is a few simple XML tags and XHTML.
>
> I suggest that before you make any more comments, you spend some time
> looking at it.
The statement you quoted me on above was a caution in the abstract about
standardizing on a complicated approach without having a few people
willing to process user contributions, primarily so that we don't
discourage such contributions. It was not directed at Anakia in
particular, hence the "or templating system." As I said, there are at
least three different suggestions floating around out there, so this was
simply my two cents on things to consider when deciding. I have
absolutely no experience with any of the proposed products, nor have I
ever pretended to.
Anyway, since it sounds like Geir has graciously volunteered to help me
form the "Ministry of Documentation" as he so cleverly coined it, the
point is more or less moot now. Users can submit plain text if they
like, and I certainly have no problems learning whatever the community
decides upon. Everybody wins.
Really, my man ... if you're going to take me to task on something,
you're going to have to learn not to quote me out of context. It's so
passe. For future reference, I never criticize an approach or product,
especially on a dev list, without thoroughly edifying myself on the
subject. (Yes, you can quote me on that. ) If you ever think that I
have, then you have misunderstood me.
Anyway, I had no idea that Anakia was your product. I will most
certainly have a look and provide my official critique. Since your
stance on JSP is dead-on accurate, and I hear that your replacement tool
is actually something of an improvement, Anakia certainly deserves a
look.
- Christopher
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project :
WAS:[TomcatDocu mentation Redactors To Hire]
Posted by Jon Stevens <jo...@latchkey.com>.
on 7/3/01 11:50 AM, "Christopher Cain" <cc...@mhsoftware.com> wrote:
> The more (most) people have to
> try and learn an extensive DTD or templating system, the less likely
> they are to bother.
I agree. That is why I came up with Anakia. It is brain dead simple to use
and runs extremely quickly. The "DTD" is a few simple XML tags and XHTML.
I suggest that before you make any more comments, you spend some time
looking at it.
:-)
-jon
--
If you come from a Perl or PHP background, JSP is a way to take
your pain to new levels. --Anonymous
<http://jakarta.apache.org/velocity/ymtd/ymtd.html>
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS:[TomcatDocu
mentation Redactors To Hire]
Posted by Christopher Cain <cc...@mhsoftware.com>.
Jon Stevens wrote:
>
> on 7/2/01 6:04 PM, "Christopher Cain" <cc...@mhsoftware.com> wrote:
>
> > I
> > have no interest in Anakia, and quite frankly, as has been pointed out
> > very astutely by Costin, I have no interest in bothering with XML for
> > the purposes of documentation. I will produce HTML docs with my favorite
> > editor and call it a task adequately completed. Asking anything beyond
> > that will more than likely be more time and effort than I am prepared to
> > invest in simple documentation.
>
> I bet you will only use a certain brand of toilet paper as well.
Dunno. I let me girlfriend handle the tough decisions like that =)
> > In short, let us please continue and decide upon how to proceed.
> > Regardless of Jon's off-topic confusion, I would really like to know how
> > the community would like to see any documentation which I may
> > contribute.
> >
> > - Christopher
>
> That's good, cause I haven't seen you contribute anything so far, Ace.
>
> The answer is simple...
>
> <?xml version="1.0"?>
> <document>
> <properties>
> <author email="ccain@mhsoftware.com">Christopher Cain</author>
> <title>Cain's Documentation</title>
> </properties>
> <body>
>
> <section name="Recent News">
> <p>
> Mr. Cain actually writes a bit of documentation instead of threatening us
> with the idea that he might do it someday if we are lucky.
> </p>
> </section>
>
> </body>
> </document>
>
> :-)
>
> -jon
Touche' ... that's fair. I have a small cache of docs that I never got
around to submitting, partly because they are install/config docs (and
the Tomcat install procedure has always been a moving target) and partly
out of sheer laziness. I will bring them up to date and cast them to the
dogs (tomcats?) before the next milestone.
There now at least three different approaches being tossed around. As
long as we come to one standardized solution, which I think is
important, I'm personally pretty doc-program agnostic. If the XML
solution being considered is as comparatively non-labor-intensive as the
rather insightful example above, then you might indeed be lucky enough
to have the gift of my documentation bestowed upon you =).
My point, badly made to be sure, was simply that it would be a good idea
to avoid over-engineering a doc solution. The more (most) people have to
try and learn an extensive DTD or templating system, the less likely
they are to bother. I have a feeling that there is an untapped wealth of
docs and notes sitting around out there, written by admins and users for
their own benefit in installation/configuration. The easier we make it,
the more contributions we will undoubtedly receive.
If a cohesive documentation system is decided upon, I would love to
start contributing. I personally agree with Pier that documentation is
easily as important than the product itself. I was very pleasantly
surprised to see a thread seriously discussing the issue of the current
"catch-as-catch-can" docs, and I got a little tweaked when it appeared
that it would flame out without resolution. For all my criticism of you
Jon, I do have to give you props on one thing. Of all the dev-list
bullies I know, you are the only one who can take as much heat as you
give, and do it with a smile. Plus most of the other bullies are so
hopelessly overmatched in verbal exchanges that it almost isn't any fun.
But you got flair, baby! =)
- Christopher