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

[GOMEZ Henri <hg...@slib.fr>]

>> Good idea,
>> 
>> We could have a tomcat-doc mailing-list, but we'll still
>> need to commit the material.
>
>I'd rather keep the documentation together with the project. When I
>(don't :) write the docs, I don't want to update two CVSes, we can give
>access to whoever wants to write it...

Many projects at jakarta may use tomcat and it would be great for them
to be able to include all or parts of Tomcat docs without having to 
include the project itself ......

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

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

Brad Cox wrote:
> 
> At 10:09 AM -0400 7/2/01, Rob S. wrote:
> >1) Developers don't write them in lieu of coding.
> >2) Users don't read them
> >3...) ?
> 
> http://www.c2.com/cgi-bin/wiki has a novel way of getting at the
> problem. Not a panacea obviously, but what is? The one at that
> address is perl-based; I can provide a tomcat/mod_jk/servlet based
> one if there's interest.

I don't have much wiki experience - however the one I am familiar with
is a huge mud ball, contentwise.

Would you describe the one above as a good example of wiki docs, or are
there better ones?

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: [Tomcat Docu mentation Redactors To Hire]

[Brad Cox <bc...@virtualschool.edu>]

At 10:09 AM -0400 7/2/01, Rob S. wrote:
>1) Developers don't write them in lieu of coding.
>2) Users don't read them
>3...) ?

http://www.c2.com/cgi-bin/wiki has a novel way of getting at the 
problem. Not a panacea obviously, but what is? The one at that 
address is perl-based; I can provide a tomcat/mod_jk/servlet based 
one if there's interest.
-- 
---
For industrial age goods there were checks and credit cards.
For everything else there is mybank.dom at http://virtualschool.edu/mybank
Brad Cox, PhD; bcox@virtualschool.edu 703 361 4751

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

[cm...@yahoo.com]

On Mon, 2 Jul 2001, Rob S. wrote:

> > I'm not sure I understand that. There are plenty of HTML editors, and 99%
> > of the people on this list know a bit of html. Nobody asked for "good
> > looking" documentation or cool formats, the content is missing.
>
> Agreed, but using Note/Text/Whatever/Pad is what the majority of people end
> up using because WYSIWYG editors have a tendency to butcher the resulting
> HTML for the next poor sap to come along and edit it.  <insert years of
> notepad versus wysiwyg editors debate>.

Not all, and even if they do - the problem is we don't have good
documentation ( content or aspect ), not what editor is used. If you
submit a good doc I'm sure we'll be able to "tidy" it, reformat it, etc,
regardless of your editor. We all know html and have a favorite editor.


> As well, nobody's *asking* for good looking docs, but if someone's willing
> to put in the time and effort (e.g. myself), what else can it do other than
> help? ;)  It's possible to have better-than-average-looking docs with a few
> well-chosen colours, etc. without burdening the build with images.

Than do it - as you can see there aren't too many people working on this
area, so nobody should be able to complain if you choose one editor or
another ( there is a nice rule to use - "if you don't like it, do it
yourself"  :-).


> I fully agree with the reorganization since right now there isn't
> really any - aside from appdev having its own subdirectory.  I'm not
> sure I understand the reasoning behind making the docs part of the
> ROOT (or /doc) web-app.  I imagine to make them accessible from the
> default Tomcat homepage?  How un/important is that?  Either way, like
> I mentioned before - organization decision, not a doc author's =)

Well, apache is doing exaclty that. Most people don't read the /doc
directory, but if they see a link on the first page they might do so.

But since I'm not working on the documentation I realize my opinion
doesn't matter as much as the doc author's preference ( since he's doing
the work :-)


> Right now if you look under the Struts repository, you'll see that all of
> the documentation is *.xml, and I imagine the build is responsible for the
> transformation...  I guess we'll have to talk to them to see how all of that
> is working out - what's the motivation?

As I said, the content is more important. Having a format that is known by
all the people ( html ) is IMHO very usefull.

If we can't get people to write documentation in HTML using any of the
existing editors, I guess it'll be much harder to ask them to learn a
XML DTD ( especially since the dtd is used only in apache, while the rest
of the world is using the docbook ). And of course, force them to use
notepad instead of wysiwyg ( even if docbook has some editors, they are
either incomplete or too expensive ). Add to that the "generation" step (
where you compile the xml to see how it'll look in html ).


Costin

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

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

> I'm not sure I understand that. There are plenty of HTML editors, and 99%
> of the people on this list know a bit of html. Nobody asked for "good
> looking" documentation or cool formats, the content is missing.

Agreed, but using Note/Text/Whatever/Pad is what the majority of people end
up using because WYSIWYG editors have a tendency to butcher the resulting
HTML for the next poor sap to come along and edit it.  <insert years of
notepad versus wysiwyg editors debate>.

As well, nobody's *asking* for good looking docs, but if someone's willing
to put in the time and effort (e.g. myself), what else can it do other than
help? ;)  It's possible to have better-than-average-looking docs with a few
well-chosen colours, etc. without burdening the build with images.

> We do need to reorganize the documentation and update it - and I agree
> with moving it part of a /doc webapplication ( instead of a doc directory
> - we can leave only the minimal README in tomcat/doc telling how to start
> tomcat in basic mode and look at the /doc webapp ).

I fully agree with the reorganization since right now there isn't really
any - aside from appdev having its own subdirectory.  I'm not sure I
understand the reasoning behind making the docs part of the ROOT (or /doc)
web-app.  I imagine to make them accessible from the default Tomcat
homepage?  How un/important is that?  Either way, like I mentioned before -
organization decision, not a doc author's =)

> But I'm not sure it would be a good idea to use something else than
> HTML ( I actually think it would be a very bad idea at this point ). Then
> people will also have to worry about learning a new set of tags ( whatever
> dtd we use), not only about content, editors will be out of question,
> we'll have to spend time working on the transformation, etc.

Right now if you look under the Struts repository, you'll see that all of
the documentation is *.xml, and I imagine the build is responsible for the
transformation...  I guess we'll have to talk to them to see how all of that
is working out - what's the motivation?

> My opinion - the documentation is not very well organized, I guess someone
> should "own" it and organize it as a book or as a standalone
> webapplication. Right now there are mostly a bunch of "notes".

Yep, very much agreed.  There needs to be some glue for all of the separate
docs floating around, rather than combining them all into one big "User's
Guide".

> Costin
> ( answering mail rather than writing the C code :-(

...or writing docs!  j/k of course =)

So in a nutshell, here I am, raring to go on documentation.  I guess I'll
work on the TC4 INSTALL ??? to describe how to get the container up and
running to view the docs.  I'm really waiting for some guidance =)

- r

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

[cm...@yahoo.com]

On Mon, 2 Jul 2001, Rob S. wrote:

> 1) People don't like to write docs, and for an open-source project, I'd say
> that's perfectly cool so long as those same people are willing to have a
> read through the docs after a major update to make sure they're coherent ;)
> For ours especially, to author them is a pain in the arse.  You should just
> have to worry about content, but 70% of it is cruddy HTML formatting.  Would

I'm not sure I understand that. There are plenty of HTML editors, and 99%
of the people on this list know a bit of html. Nobody asked for "good
looking" documentation or cool formats, the content is missing.

We do need to reorganize the documentation and update it - and I agree
with moving it part of a /doc webapplication ( instead of a doc directory
- we can leave only the minimal README in tomcat/doc telling how to start
tomcat in basic mode and look at the /doc webapp ).

But I'm not sure it would be a good idea to use something else than
HTML ( I actually think it would be a very bad idea at this point ). Then
people will also have to worry about learning a new set of tags ( whatever
dtd we use), not only about content, editors will be out of question,
we'll have to spend time working on the transformation, etc.

And we'll certaninly have some flame wars about what DTD to use ( docbook
is the standard outside apache, stylebook is used in many apache projects
- which one should we use ? Many believe the first is too complex, but
some believe standards are important ). A good news - it seems AbiWord (
yet another editor ) can generate some basic docbook, and the gui is not
that bad ( amazingly, it can save as palm pdb, as well as latex ! ).

> 2) Why don't (a lot) of people read them?  I dunno...  I know that
> personally, I have a tendency to gloss over mounds of documentation, even if

My opinion - the documentation is not very well organized, I guess someone
should "own" it and organize it as a book or as a standalone
webapplication. Right now there are mostly a bunch of "notes".

Speaking of notes, it would be very cool if we start a new directory and
colect the relevant mail from this list ( proposal, technical arguments,
etc). The list is full of crap, and extracting the usefull info is quite
difficult.

Costin
( answering mail rather than writing the C code :-(

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

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

> >I'd rather keep the documentation together with the project. When I
> >(don't :) write the docs, I don't want to update two CVSes, we can give
> >access to whoever wants to write it...
>
> Many projects at jakarta may use tomcat and it would be great for them
> to be able to include all or parts of Tomcat docs without having to
> include the project itself ......

But that's really an organizational problem, not a documentation problem,
no?  I guess I'm not sure how creating a new project is going to get people
to write or read documentation? =)

What are the 'problems' with documentation?

1) Developers don't write them in lieu of coding.
2) Users don't read them
3...) ?

1) People don't like to write docs, and for an open-source project, I'd say
that's perfectly cool so long as those same people are willing to have a
read through the docs after a major update to make sure they're coherent ;)
For ours especially, to author them is a pain in the arse.  You should just
have to worry about content, but 70% of it is cruddy HTML formatting.  Would
developers write more docs if they didn't have to go through the pain of
HTML?  I noticed that the Struts docs are in XHTML using a single style to
render them all.  I wonder if we could toss a small front-end over something
like that, that allowed you to do like 90% of the doc writing work via the
web.  Any crazy custom formatting or anything and you'd have to edit the
.xml directly.  Dunno, just brainstorming here...  The TC4 docs are part of
a web-app already (re: ROOT/docs).  I'd be extremely interested in doing
something like if everyone thought it was a good thing.

2) Why don't (a lot) of people read them?  I dunno...  I know that
personally, I have a tendency to gloss over mounds of documentation, even if
it's Good For Me(tm).  Hell, it works for computer games, why not Tomcat?
This is why I proposed we break the docs up into more bite-size chunks.  I'm
sure there are lots of other 'problems' with them, but we receive very
little feedback aside from "TOMCAT SUCKS!" so it's hard to do anything about
it =)

Thoughts?

- r