You are viewing a plain text version of this content. The canonical link for it is here.
Posted to general@jakarta.apache.org by Luc Saint-Elie <ls...@imaginet.fr> on 1999/07/18 12:28:50 UTC
Proposal : Jakarta Documentation Project
Hello folks
As this message is pretty long here is an abstract :
"As Jakarta is just starting, perhaps its the right time to launch in
parallel a Jakarta Documentation Project (in the spirit of the Linux
Documentation Project http://metalab.unc.edu/LDP/ )"
The long stuff :
Following the "I volunteer" thread :
I'm currently trying jwsdk 1.0-ea and as a java server side technologies
hobbyist I would love to see Jakarta Project avoid all the pitfalls jwsdk
folks are compiling
Right now in its released form its easily possible to run the examples but
its nearly impossible to seriously try this software, and I hardly believe
that a new technology user's main goal is only to run examples.
Why is JWSDK nearly unusable ?
Because it lacks some very basic stuff as : "how to use it"
It very difficult to find (you really have to guess) how to set it up, what
are the mandatory files/folders, where to put what and how to call what. By
"how to set it up" I don't mean "how to set up the class path" but things
like "how to reuse web application I've previously developed or new web
application I would like to develop with/for this server".
Result, its a very powerful tool to run accompanying examples.
With a rather new and uncommonly known technology as JSP/Servlet is,
solution providers must let users focus on
learning/evaluating/test/deploying the technology more than
learning/evaluating/testing .. the underlying software (even if this
underlying software is important)
So.. as in this list there are two kind of people : developers and "end
users", I suppose it would be a great thing to separate stuff in two,
letting developers develop and end users write down in
as-close-to-real-time-as-possible the accompanying documentation.
I'm not sure that developers have time enough to write down sufficient docs
for the software they develop (its probably JWSDK 1.0-ea guys situation)
and even if they had time, I'm not sure they are the best suited to do this
task (difficult to explain something you have done because every thing can
be seen as evident).
In order to do this a little planning could be of some help and some
answers could be useful. For example IMHO questions a new user to a new
technology may wonder is :
a) What is Jakarta ? How does it relate to other Java technologies and
other web servers?
b) How to I install ?
c) How do I configure ?
This is IMHO a crucial point, and this point is related to the next one
- How do I reuse stuff I've developed before targeted to other software
I see this question as fundamental, more important than the "how do I run a
HelloWorld servlet". Jakarta audience will be composed of Web
administrators and Web developers with real life needs (do you know any
body in real life needing to say "Hello" to the World using a web server ?)
and for some of them, with stuff already developed for Jserv, Jrun or others.
In order to follow Jakarta path this people will need to be able to run
their existing developments.
d) How to maintain/administer/extend/fine tune ?
e) How to update ?
f).....
So in order to start an operational action, perhaps some basic things may
be defined, for example :
- will jakarta settings be based upon jwsdk 1.0-ea way to define things,
will its settings be based on jwsdk1.0-ea's one ?
If the answer is yes, Its probably possible right now to start a "real" doc
for jwsdk1.0-ea (with in mind that perhaps parts will change for Jakarta)
and adapt it in real time as sown as jakarta development progresses to
insure that at any time, people that arrive in the jakarta world will find
a sufficient documentation to be using it directly (i.e. be blocked by the
level of development of the software, not by configuration or usage problems).
Say in a other way (and the following sentence is by no mean offensive for
the huge work Apache Project guys are doing and have done) it would be a
great idea to not reproduce the Jserv effect (Jserv is a fantastic product
but Jserv setting is too esoteric for a newcomer, especially in a field
where a lot of stuff no directly Jserv related are new to this newcomer).
As Jakarta is just starting, perhaps its the right time to launch in
parallel a Jakarta Documentation Project (in the spirit of the Linux
documentation Project http://metalab.unc.edu/LDP/ )
Luc
+------------------------------------------------+
| Luc Saint-Elie |
| 75018 Paris France |
| Tel: 1(212)894 3713 ext: 0012 |
| email : luc@interpasnet.com |
+------------------------------------------------+
| Java Server Side Open Source technologies |
| http://www.interpasnet.com/JSS |
+------------------------------------------------+
Re: Proposal : Jakarta Documentation Project
Posted by Stefano Mazzocchi <st...@apache.org>.
Luc Saint-Elie wrote:
> As Jakarta is just starting, perhaps its the right time to launch in
> parallel a Jakarta Documentation Project (in the spirit of the Linux
> documentation Project http://metalab.unc.edu/LDP/ )
I totally agree (and so will probably everybody else) that you're right:
documentation is _really_ important for the success of a software
product, even if you have the best of all source of knowledge (the
source code) in your hands, since you probably don't have the time to
look at it do find out what it does.
So, yes, I would welcome such a project, but only if officially stored
inside the apache.org domain. I believe this is really important: linux
grew very decentralized and this wasted a lot of time to allow people to
find things and to get big enough to create communities and noospheres
around them.
Jakarta should be highly centralized, both for software and for any
other related resources (such as documentation, general information,
bug-reports, source repository, blah blah)
So, yes, +1 to create another project inside the Jakarta umbrella to
host documentation for the project. This doesn't necessary mean
"documentation for Tomcat", but rather general documentation
(whitepapers, user guides, man pages and such) for the arguments touched
by the Jakarta project.
How does it sound?
--
Stefano Mazzocchi A language that doesn't affect the way you
think about programming, is not worth knowing.
<st...@apache.org> Alan J. Perlis
---------------------------------------------------------------------
Re: Proposal : Jakarta Documentation Project
Posted by ch...@hamptons.com.
At 07:36 AM 7/19/99 +0200, you wrote:
>Chris
>
>Its not exactly the same thing.
>Several people around maintain some doc about what's happening in the JSP
>world. To name a few lets name the excellent R. Wowles JSP FAQ
>(http://www.esperanto.org.nz/jsp/jspfaq.html).
>What I as proposing was not to start another personal action but to add to
>the Jakarta project a documentation part.
Oh I agree. My little Jakarta4All thing isn't an independent effort. It's
under the Jakarta umbrella, in that when the Jakarta folks get around to
taking it, it's theirs. I just wanted to organize some ideas and some
effort before that, and it seemed silly to wait around for the busy Jakarta
people to get around to this low priority, when web space & free lists were
available.
But no, this isn't an independent effort - indeed, it couldn't possibly be,
as the goal of making Jakarta as easy to use as possible is much too big
for one person (it's a lot bigger than a JSP FAQ, for example). So don't
worry about that. It's just me trying to get things rolling.
- Chris
Re: Proposal : Jakarta Documentation Project
Posted by Luc Saint-Elie <ls...@imaginet.fr>.
Chris
Its not exactly the same thing.
Several people around maintain some doc about what's happening in the JSP
world. To name a few lets name the excellent R. Wowles JSP FAQ
(http://www.esperanto.org.nz/jsp/jspfaq.html).
What I as proposing was not to start another personal action but to add to
the Jakarta project a documentation part.
If it seem an acceptable idea (apparently this is not very clear) the best
and natural way would be to do this under jakarta.apache.org umbrella. The
only reasons to do this outside would be some strategic reasons (as I was
writing yesterday, if some vendors where willing to participate) or if
people involved in jakarta.apache.org maintenance have not enough time to
insure this hosting.
Richard,
I'm not sure that becoming famous would be the best motivation :-)
(Of course if it appears that a lot of very beautiful women are willing to
use these technologies my position would quickly evolve)
Le 18:06 18/07/99 -0400, chrisl@hamptons.com wrote:
>Luc -
>[..]
>I think that for Open Source projects such as Jakarta, it makes a great
>deal of sense for there to be a group doing devlopment and a group doing
>documentation, etc, etc.
>To this end I started a little Web site and a little mailing list, called
>Jakarta For All, a weel or so ago. It's very rugged now (partly because I'm
>getting ready to move to Houston for a while), but I believe we have nearly
>the same goals and vision. I am careful not to call Jakarta For All a
>'documentation project', because J.F.A's goal and purpose is to make
>Jakarta as easy to understand and use as possible. This means docs, but it
>also means much much more.
Le 12:00 19/07/99 +1000, grumpy@cyber4.org wrote
>I guess the other thing about the documentation project is that
>this is new, exciting and when we come out of it Tim O'Reilly
>can publish the book and we'll all be famous (not that fame
>is a driving motivation). But it is the opportunity to be at the
>start of something new and dynamic (and no, I'm not a
>sales or marketing person)
+------------------------------------------------+
| Luc Saint-Elie |
| 75018 Paris France |
| Tel: 1(212)894 3713 ext: 0012 |
| email : luc@interpasnet.com |
+------------------------------------------------+
| Java Server Side Open Source technologies |
| http://www.interpasnet.com/JSS |
+------------------------------------------------+
Re: Proposal : Jakarta Documentation Project
Posted by Luc Saint-Elie <ls...@imaginet.fr>.
Hello folks
Here is a more "formal" version of my previous message:
1) What is this stuff about ?
==============================
As Jakarta is just starting, perhaps its the right time to launch in
parallel of the development effort a Jakarta Documentation Project in the
spirit of the Linux Documentation Project (see it at
http://metalab.unc.edu/LDP).
The following is NOT about development but about documentation.
2) Why do you think its is necessary?
====================================
For two reasons :
* These technologies are brand new and there are not a lot of documentation
around
(As one of those who try to group this documentation I can say that its a
pretty hard job :-))
* These technologies are intended for users (Web administrators,
developers..) and these guys doesn't want to succeed in setting up their
Web servers, they want to succeed in setting up their Web applications..
not exactly the same thing. On the other hand there are several questions
that are unanswered in the Web Administration field (Ie JSP/Servlet
security form an ISP perspective)
This is especially true in the NT world where people are not used to mine
the web in order to (perhaps) find how their software works. I think that
broad acceptance of Java server side technologies requires to touch the NT
world.
In the NT world you never have to find some stuff to learn "how it works"
(on the other hand you often need help to find "why it doesn't" :-) )
Apache/UNIX rules in the Web/Internet world, but NT(ASP/Domino) is VERY
strong in the Web/intranet world, this must (IMHO) be taken in account.
3) But there is not yet any Jakarta code so all
this buzz is irrelevant.
Is it not time for you to renounce to alcohol ?
===============================================
Not at all.
Its exactly because there is not yet any Jakarta code released that I think
it time to set
up a documentation project.
When the code will start to flow it will be too late
Right now we have (little) time to think about how stuff must be set up
4) Why a Jakarta Documentation Project instead of
a simpler Jakarta documentation ?
=================================================
Because JSP/Servlet technology covers a broad range of issues, and will
lead to a broad range of questions for a broad range of users types and a
broad range of situations
Also because a unified documentation leads to unified level of information.
By setting a large set of documents it would possible to have documents for
different publics, from a Howto set up your classpath to howto launch a
spacial engine from a satellite-hosted Web service.
5) Yes but there are FAQs
==========================
No problem, the Jakarta Documentation Project doesn't intend to rule or
reinvent the world.
If FAQs of other stuff exists.. we'll add them (is their respective authors
are OK of course)
6) What kind of documents this so called Jakarta Documentation project will
propose ?
============================================================================
========
This project will consists in several kind of documents (again copied from
the LPD):
a) HOW-TOs
b) FAQs (see question #4)
c) Books and white papers
d) Others documentations
7) How would this JDP relate to Jakarta Project ?
=================================================
In fact it depends.
If Jakarta Project guys are interested it could be part of Jakarta Project
But if Jakarta Project guys aren't interested (for some reasons included
the lack of time)
it could be an independent effort.
By independent I mean "something that doesn't engage the Jakarta team", it
obvious that a documentation on Jakarta can't be done separately from
Jakarta development.
There is another reason that make me think that this could be a brother
project but not an entirety included project : the industry support. I
think that beside a Open Source development spirit, it may be useful
to make appear a Open Source Advertising spirit. I'm trying to start this
on my own site without any success until now. I mean that I've been
contacted by several (3) vendors that asked "what are your advertising
rates ?" and I answered "I don't need money I need content, be clever,
demonstrate the excellence of your products by demonstrating your knowledge
by providing tutorials and other papers instead of banners, and you'll have
as much space as you need.
Until now I've had no success, but I still think its a good idea. It would
be interesting if it is of no risk for the code effort (I mean if its
impossible to say Jakarta is an Microraclibm submarine).
8) But who are you ? what would be your role ?
==============================================
I'm just a guy interested in java use on the server side.
I maintain a personal site where I try to group java server side stuff and
its a very difficult effort, so I'm not at all able by my own to do this.
This must be a collaborative effort.
If needed I can provide web space on my server (of course if Jakarta
Project people think this must be a Jakarta element this could be hosted on
jakarta.apache.org).
To be really clear this would be a very exciting project if and only if
others are interested. I don't intend to start something like that alone.
9) What would be the planning ?
===============================
The firsts steps would be :
a) see if other people are interested and lists the volunteers
b) wait for the Jakarta Project team OK. Its clear that this would have no
sense if this OK is not obtained. The goal is not to be a competitor but a
support and an help to the development effort.
c) Set up a list of FAQs and Howtos to be written (or to be collected and
in this case contact the authors)
d) set up a web site
e) fire !
10) What is this strange smelling?
==================================
....I'm sorry.. I smoke the pipe..
+------------------------------------------------+
| Luc Saint-Elie |
| 75018 Paris France |
| Tel: 1(212)894 3713 ext: 0012 |
| email : luc@interpasnet.com |
+------------------------------------------------+
| Java Server Side Open Source technologies |
| http://www.interpasnet.com/JSS |
+------------------------------------------------+
Re: Proposal : Jakarta Documentation Project
Posted by ch...@hamptons.com.
Luc -
We seem to think very muech alike. I too get frustrated by software that is
quirky and had to learn, even when it is free, and yes, I have the same
opinioin of JSWDK in particular.
I think that for Open Source projects such as Jakarta, it makes a great
deal of sense for there to be a group doing devlopment and a group doing
documentation, etc, etc.
To this end I started a little Web site and a little mailing list, called
Jakarta For All, a weel or so ago. It's very rugged now (partly because I'm
getting ready to move to Houston for a while), but I believe we have nearly
the same goals and vision. I am careful not to call Jakarta For All a
'documentation project', because J.F.A's goal and purpose is to make
Jakarta as easy to understand and use as possible. This means docs, but it
also means much much more.
The URL is at http://www.tourneyland.com/Jakarta4All/whatitis.html. The
mailing list is Jakarta4All@onelist.com. TO join it, you have to go to
www.onelist.com and get an account, and then subscribe - not a big deal.
These are probably temporary, as this sort of thing should migrate over to
Jakarta's home at some point. Also, I don't intend to 'own' the project - I
just wanted to get it started. (If it should fall short of its potential, I
may maintain an independent effort, but other than that it's as up for
grabs as Jakarta itself.
I look forward to hearing from you!
Chris