You are viewing a plain text version of this content. The canonical link for it is here.
Posted to general@jakarta.apache.org by David Joham <dj...@criadvantage.com> on 1999/07/20 04:27:14 UTC

Jakarta Documentation Project

Well, it looks like we have a number of people interested in helping out
with the development of some really good documentation for the Jakarta
project. To which I have to say "Cool!". 

Its getting to the time where I would like to encourage discussion on how we
should proceed with this endeavor. I'll start things off by giving a broad
outline of where I would like to see the project go.

I would like to have a separate mailing list for the Jakarta Documentation
Project. This would serve a number of purposes including potentially growing
into part of the documentation itself. This would require someone at the
Apache organization to setup and administer presumably.

I'd also like to see a web site set up on the Apache domain where we can
release our work. This will be our central repository for knowledge and the
"official" documentation area. We'd need to set up some form of scheme that
would allow selected contributors to post reviewed and accepted
documentation, sample code, etc. In addition, some way of posting
observations and titbits of knowledge outside of what's already covered
should be available. For the latter, the FAQ-o-Matic would serve our purpose
well, I think.

For development work, I think we can host a box (or boxes) somewhere on the
net that we can thrash on while we test whether our documentation "works" or
not. There have been a couple of different offers to me for hosting. I don't
really see a need for Apache to host this stuff.

Well, since I'm aptly demonstrating my habit of being long winded, I'll wrap
up with a snippet of a post I sent to the Jakarta4All list last night
outlining some other documentation goals I have in mind for this project...

What is Jakarta? 

What makes Jakarta tick? Anyone ever see a Microsoft presentation of an
N-tier application? Dilbert's boss could understand it. 

How do I make it work on my (Linux, NT, BSD, <insert favorite OS here>) box 

I've got a standard install of Apache. How do I upgrade? 

OK, now that I've got it to say "hello world" how do I really get it to
work? (this step took me two days with JServ. Seems someone forgot to
document the need to "declare" a servlett zone in one of the half a million
configuration files...)

Lots and lots of example code. I think this is critical for developers. 

JSP documentation. (Chris mentioned a project underway for this. How can we
leverage?) At one time, MS had a really nice page up documenting JavaScript.
They have since made the page IE exlusive and locked me and my Linux box
out. However, the idea of on-line documentation such as this appeals to me. 

Perhaps a configuration tool? With what? HTML, JAVA, JSP, All of the above? 

We will need to set up a review process not only internally, but with the
geeks writing the code to make sure we're not putting our foot in our
mouths.


The way I see it, we need lots of different skill sets for this project: 
  1) Documenters. People who know how to make Grandma be able to install and
work with this
  stuff 
  2) Code Junkies. People who can write and document example code so even an
inexperienced
  Java programmer can get it to work.
  3) Artsy people. The best documentation will never be used unless its
presented in a way
  that's user friendly and easy to peruse. It helps a lot if it looks good
too. I really like     how Linux.com is set up as an example.


All right, I've been wordy enough. Comments are very welcome...

David

Re: Jakarta Documentation Project

Posted by Luc Saint-Elie <ls...@imaginet.fr>.
+1

Yes, I agree, but i think bridges must be set between the developers lists 
and the documentation lists to avoid unparralel evolution.

The reason why I first proposed to start a Jakarta Documentation Project 
(instead of a FAQ or something else) is that as Jakarta code has not 
(publicly) started, its right on time to set up the framework of what would 
become a documentation project the whole stuff based on the idea that 
worked pretty well in the Linux World.
By "set up the framework" I mean:
- Define the format used (HowTos, FAQs, classical text)
- Define the rules for the various formats (what goes in a HowTos, what 
goes in a FAQ..)
- Define the skeleton of each family (for example : a "HowTo install on" 
for each plate-form/OS)
- and of course define who is "responsible" for what, but if the framework 
is clear, this question might be easily resolved

The goal (IMHO) would be to have an (of course) empty but as complete as 
possible framework ready when the code starts to flow, with people ready to 
fill the items as soon as it is possible considering the development effort.

This would have two advantages :
* Concentrate on the docs itself and not on the form of the doc
* Give people that arrive in the project (as lurkers, users, 
developers....) the sensation of a rather clear path and the insurance that 
questions that are not yet covered by documentation have been taken in 
account and will be addressed in an undefined future.
* Allow people that are competent in one precise area and would have not be 
tempted to participate to a more classical documentation, to propose their 
help for a precise point.

This kind of discussion would be disturbing in a general list and must 
probably be conducted in a separate one.

But once this framework is OK for every body, I'm not sure that a separate 
list would be the evident choice as I will be necessary very often to have 
control, contact or explanation from the developers...

Luc

+------------------------------------------------+
| Luc Saint-Elie                                 |
| 53, rue Caulaincourt                           |
| 75018  Paris France                            |
| Tel: 01 42 52 09 62 / 06 12 90 19 65           |
| email : team@interpasnet.com                   |
+------------------------------------------------+
|  Java Server Side  Open Source technologies    |
|       http://www.interpasnet.com/JSS           |
+------------------------------------------------+

Re: Jakarta Documentation Project

Posted by James Davidson <du...@x180.com>.
>      Like the ancient agora, every active member who deserves it has the
> right

Crap. Sorry for the lousy word wrap. :(

The essential part:

+1 Yes, agree, or the action should be performed. On some issues, this
vote is only binding if the voter has tested the action on their own
system(s).
 
±0 Abstain, no opinion, or I am happy to let the other group members
decide this issue. An abstention may have detrimental effects if too
many people abstain.

-1 No. On issues where consensus is required, this vote counts as a
veto. All vetoes must include an explanation of why the veto is
appropriate. A veto with no explanation is void. No veto can be
overruled. If you disagree with the veto, you should lobby the person
who cast the veto. Voters intending to veto an action item should make
their opinions known to the group immediately, so that the problem can
be remedied as early as possible.

-- 
James Davidson       
duncan@eng.sun.com                http://java.sun.com/products/servlet
duncan@x180.com                              http://jakarta.apache.org
!try; do()                                              PGP:0x7D776205

Re: Jakarta Documentation Project

Posted by James Davidson <du...@x180.com>.
> I would like to have a separate mailing list for the Jakarta Documentation
> Project.

Ok... The general rules of engagment still haven't been layed out -- but
to go with the current jserv model, the way we do that is to propose and
vote on such a mailing list. It seems like there's wide desire for this. 

So, since we don't yet have our process house in order, let's steal from
the java.apache.org consitution (thanks in advance Stefano!):

     Voting

     Like the ancient agora, every active member who deserves it has the
right
     to vote. Each vote can be made in one of three flavors (following
Apache
     style): 

          +1 Yes, agree, or the action should be performed. On some
issues,
          this vote is only binding if the voter has tested the action
on their
          own system(s). 

          ±0 Abstain, no opinion, or I am happy to let the other group
          members decide this issue. An abstention may have detrimental
          effects if too many people abstain. 

          -1 No. On issues where consensus is required, this vote counts
as a
          veto. All vetoes must include an explanation of why the veto
is
          appropriate. A veto with no explanation is void. No veto can
be
          overruled. If you disagree with the veto, you should lobby the
          person who cast the veto. Voters intending to veto an action
item
          should make their opinions known to the group immediately, so
that
          the problem can be remedied as early as possible. 

     An action item requiring consensus approval must receive at least 3
     binding +1 votes and no vetoes. An action item requiring majority
     approval must receive at least 3 binding +1 votes and more +1 votes
     than -1 votes (i.e., a majority with a minimum quorum of three
positive
     votes). All other action items are considered to have lazy approval
until
     someone votes -1, after which point they are decided by either
consensus
     or a majority vote, depending upon the type of action item. 

     The act of voting carries certain obligations because voting
members are
     not only stating their opinion, they are agreeing to help on the
voted issue.
     Since we are all volunteers, members often become inactive for
periods of
     time in order to take care of their "real jobs" or devote more time
to other
     projects. It is therefore unlikely that the entire group membership
will vote
     on every issue. To account for this, all voting decisions are based
on a
     minimum quorum.

     Every active developer may request a voting on an issue sending a
     message with a Subject beginning with [VOTE]

The only thing that I'd add to this is that votes should have an expiry
at which time they are closed. I'll be posting the [VOTE] post in just a
minute.

> I'd also like to see a web site set up on the Apache domain where we can
> release our work. 

How about a sub section of the jakarta web site? Say
jakarta.apache.org/docs? With all the activity going on, it's pretty
obvious we need to get the web site open'd up for more contribution. 

Jon, if this works for David, can we set up a temp CVS tree on
working-dogs.com for the entire website and give David permissions to
write, as well as setting up the same system that you guys use for
java.apache.org to get the content onto the site? I don't have the
master Jakarta CVS machine up yet and probably won't for a little while
more. In the mean time, we've got lots of stuff to put onto the website:

	1) docs
	2) craigs "do" list
	3) the administration/config proposals

This stuff shouldn't be blocked just cause the big CVS machine that
we're providing isn't up yet. 

-- 
James Davidson       
duncan@eng.sun.com                http://java.sun.com/products/servlet
duncan@x180.com                              http://jakarta.apache.org
!try; do()                                              PGP:0x7D776205

Re: Jakarta Documentation Project

Posted by Jim Richards <gr...@cyber4.org>.
On the Documentation Project ...

>Lots and lots of example code. I think this is critical for developers. 

Does the documentation for the internals for the Josper and Tomcat 
development process get included? I assume the developers
will write documentation as they go (they will, won't they)
or at least have something at the start as a functional and technical
specification ...

Like, who is going to do the functional specification? The technical one
as well? We need those before coding cam start really otherwise 
things will get messy ...


----
You are the simulacrum of my dreams
 and the signifier of my desires

Mr Grumpy ... come and visit his home!
	http://www.cyber4.org/members/grumpy/index.html