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