Marc said that the following people are interested in helping out with the
jBoss documentation:
>PARTICIPANTS + INTEREST
>=======================
>
>Kevin Boone <[EMAIL PROTECTED]>, documentation
>Ken Jenks <[EMAIL PROTECTED]>, documentation
>Andy Dwelly <[EMAIL PROTECTED]>, developer documentation
>Steve Qwee <[EMAIL PROTECTED]>, Documentation QA
Anyone else interested, please drop me a line.
There are two kinds of developers who need documentation, bean developers
(those who use jBoss to develop their beans, but who don't muck around with
the jBoss internals) and jBoss developers (those who muck around with the
internals -- presumably, they're also bean developers).
Here's my evil scheme. We'll start from the current bean developer
documentation on the Web site <http://jboss.org/> and work forward to get
"Getting Started" tutorials that work for both Linux and Windows.
I'd also like to develop detailed instructions to help beginning EJB
programmers who are reading the major EJB books, like Monson-Haefel's
"Enterprise JavaBeans" (2nd Edition). I'm working on instructions for how
to run those examples, for both Windows and Linux. If you have another
book, or if you use EJB examples from a Web site, let's try to do the same
thing there.
To Kevin's CMP example, we'll add a BMP example.
I'd also like to demonstrate a complete multi-tier J2EE implementation,
from database to EJB to servlet to applet. I have all but the applet part
working. Anyone want to help with that final tier?
We'll also add more advanced information for bean developers, including
how-to documents for configuring different database back-ends.
At the same time, we can start getting some more organized jBoss developer
documentation in place. Currently, it's pretty hard to jump in and
contribute to jBoss, but an Open Source project always needs new blood. I
think we need
(1) an overview of the jBoss Open Source development process including
Bugzilla, CVS and the GPL,
(2) an introduction to the jBoss architecture (with its plug-ins) and
location of the javadoc HTML,
(3) a Web page for each jBoss development team showing team members, to-do
lists, overviews like this one, etc.,
(4) a step-by-step tutorial on how to do a CVS checkout (for Windows and
Unix),
(5) step-by-step instructions on how to edit, compile and test one class,
(6) how to run the jBoss test suite,
(7) how to check your changes back in to CVS.
I would find it very helpful to have a JBuilder project file that makes it
dead simple to compile, edit and debug changes in the jBoss .java files,
but it's probably too much work to maintain project files for each popular IDE.
There are two big issues in writing jBoss documentation, platforms and paths.
Since jBoss works on almost every platform and writing detailed
instructions is platform-specific, we'd be swamped if we tried to write
instructions for every platform, but we'd lose the specificity needed by
beginning users if we make the instructions non-platform-specific. Kevin
started with Linux users, which is a good, large subset of our user
population, but we should obviously include Windows users as well. (What
other platforms? Solaris? Or lump them in with Linux? Macintosh?)
On whatever platform, each user will choose to install jBoss in some path.
Kevin chose /usr/lib/jboss as the default; I changed that to
/usr/local/jboss. On Windows, the installer plunks jBoss into C:\Program
Files\jboss2\ by default. But the installation path affects almost every
procedure and every script in the documentation.
I think we can address these problems by asking the user which platform
he's using (from a pull-down menu) and which path he's installed jBoss in
(from a text entry box) and setting cookies on the user's machine. We can
then use those cookies to customize the jBoss documentation for the user's
installation (platform and path). This makes our job a little more
difficult, writing and doing QA on the documentation, but I think one set
of documentation with this user-selectable option is easier to maintain
than two sets of documentation (one for Windows and one for Linux),
containing two sets of instructions (one for default paths, with vague
hints about how to deal with non-standard paths, as is often done with this
type of documentation).
I'll work on some client-side JavaScript to do that. I think JavaScript
better than server-side scripting for this particular job because we can
all run it and test it on our local machines, with no server-side
components to compile or test.
What do you think?
-- Ken Jenks, http://abiblion.com/
Tools for reading.
