Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project :WAS:[TomcatDocumentation Redactors To Hire]

["Geir Magnusson Jr." <ge...@optonline.net>]

Christopher Cain wrote:
> 
> "Geir Magnusson Jr." wrote:
> >
> > Documentation is just as valuable as the software...
> 
> I could not agree more. What I meant by "simple" documentation is that
> I, personally, do not have to requisite expertise to write in-depth docs
> on the various inner workings of Tomcat. Since there are a fair amount
> of short docs on specific aspects, such as the NT service, running the
> connectors in-process, etc., we should keep in mind that the frequency
> of submissions of such "simple" documentation by users is inversely
> proportionate to the complexity of the solution we choose.

I actually don't follow the logic here.

You said 

"I have no interest in bothering with XML for the purposes of
documentation."

Writing XML docs is easy.  For doing docs compatible with the 'implied'
anakia DTD, it's hardly different than HTML.

The nice part is that they can be managed and restyled.

> If I am Joe
> User, and I put together some notes on how I managed to get a connector
> configured under Windoze 2000, am I likely to try and learn a complex
> DTD in order to submit it to the project, especially if I have a rather
> demanding day job? Probably not. Am I likely to download a program,
> learn it, and generate the right format? Probably not.

Again, I am not sure this parses for me.  If you let people submit docs
in whatever randomly broken variant of HTML their HTML editor generates,
the submissions will be far less useful than just plain text. 

So have a policy : 

0) All documentation is appreciated.
1) If you can, submit docs using our XML DTD. It makes it easy to
integrate into the rest of the documentation.  Here is a sample
template.  Fill in the content section.
2) If you can't we still appreciate your effort.  Please send us notes
and docs in ASCII text format.

In the beginning of the Velocity project, we had someone dedicated to
doing documentation.  He wasn't technical, but was able to grok what
needed do be done, and styled and formatted whatever was offered.  He
even watched the mail lists to get examples.

I would be someone might volunteer to be Minister of Documentation...

> Now if a few people on the list are willing to take text and/or HTML
> submissions and generate the "approved" format, then so much the better.
> Since I have now opened my mouth and made a suggestion on what *others*
> should do with their OSS time, I suppose I am more or less volunteering
> to help up in that regard. 

Great!

> But my point was simple to caution against an
> over-engineered approach to documentation without a few people stepping
> forward to help "own" Tomcat documentation. Otherwise it will only lead
> to less documentation.

That's not how I read your post.  However, I will assume now it was my
misunderstanding and leave it at 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.
> >
> > Didn't you just say that you are going to do it in HTML and declare
> > victory no matter what?
> 
> Actually, what I said was that I would declare it a "task adequately
> completed." =)
> 
> What I meant to imply was that let's not make generating documentation a
> class project.

What you get if you don't is a mess.

> Like most non-critical software, at the end of the day it
> doesn't really matter how many bells and whistles the solution provides
> if no one has the inclination or the time to learn how to use a complex
> package. We are all programmers, and the easier the solution the more
> likely it is we will deign to actually bother with documentation.

XML isn't that hard.  Give it a whirl sometime..
 
> My delivery was admitedly a little pointed and unclear because I was
> having a little fun with Jon. But that's okay, he loves the abuse. =)

I am sure that's why he dedicates so much time to this. 

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:[TomcatDocumentation Redactors To Hire]

[Christopher Cain <cc...@mhsoftware.com>]

"Geir Magnusson Jr." wrote:
> 
[snip]

Most of this was under the assumption that there would be no one
volunteer to dedicate additional time and energy in a little cabal of
people to take the lead on organizing and standardizing Tomcat
documention. Since I have now gone from, "Bah! Don't pester me about
learning Anakia or any other damn thing for simple docs," to, "Cool,
let's organize and standardize this bad boy," and since you are offering
to devote time as well, all my previous grumblings are officially
withdrawn. Under an organized approach, which I will damn well help out
with, I can live with almost any solution.

> > If I am Joe
> > User, and I put together some notes on how I managed to get a connector
> > configured under Windoze 2000, am I likely to try and learn a complex
> > DTD in order to submit it to the project, especially if I have a rather
> > demanding day job? Probably not. Am I likely to download a program,
> > learn it, and generate the right format? Probably not.
> 
> Again, I am not sure this parses for me.  If you let people submit docs
> in whatever randomly broken variant of HTML their HTML editor generates,
> the submissions will be far less useful than just plain text.
> 
> So have a policy :
> 
> 0) All documentation is appreciated.
> 1) If you can, submit docs using our XML DTD. It makes it easy to
> integrate into the rest of the documentation.  Here is a sample
> template.  Fill in the content section.
> 2) If you can't we still appreciate your effort.  Please send us notes
> and docs in ASCII text format.
>
> In the beginning of the Velocity project, we had someone dedicated to
> doing documentation.  He wasn't technical, but was able to grok what
> needed do be done, and styled and formatted whatever was offered.  He
> even watched the mail lists to get examples.
> 
> I would be someone might volunteer to be Minister of Documentation...

You and I are in complete agreement here. I had considered that people
would hand-code the HTML, but maybe you're right in that that might be
too much to hope for. God help us all if people start submitting Front
Page-generated docs!

I think your policy suggestion makes perfect sense. Again, as long as
there are people willing to help out with accepting/converting any user
docs instead of simply telling people of varying skill levels to go
learn Anakia or whatever, my reservations about the complexity of the
approach vanish. My statements about keeping it as simple as possible,
possibly HTML, were under the assumption that no one would continue to
be "in charge" of documentation. I just don't want to see it get any
harder for docs to get included in Tomcat ... it's already pretty
hit-and-miss as it is.

> XML isn't that hard.  Give it a whirl sometime..

I have a pretty reasonable amount of experience in XML. It wasn't really
a question of knowledge, it was more a question of how much overhead it
would add. I had visions of trying to install and configure some
screwball display parser for half a day just to preview my documentation
in order to get it accepted. Since it appears that I have unwittingly
placed myself into the newly-forming "Ministry of Documentation",
however, I guess that's not much of an issue anymore. =)

Seriously, though, I think your proposal makes sense. I will certainly
assist in this new, more organized approach to TC documentation. As I
said, I have no real opinion about which solution to go with. XML, HTML
(no FrontPage!), DHTML, XHTML ... whatever, I'll let you guys sort it
out. I kinda liked the idea of having it set up as a new context and
installed along with Tomcat, though. That would be pretty hip, and the
idea has merit.

- Christopher "His-love-is-real,-but-his-documentation-is-not" Cain

RE: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project:WAS:[TomcatDocumentation Redactors To Hire]

["Rob S." <rs...@home.com>]

> Writing XML docs is easy.  For doing docs compatible with the 'implied'
> anakia DTD, it's hardly different than HTML.

Agreed...  I'm not sure that some of the detractors have checked out the
existing XML docs in Struts.  It may as well be XHTML for all its
similarities to HTML.

- r