Ken, please add this to your bugzilla thread.
This "high level mission statement" mail is a good example of great
cross-posting (bugzilla+jboss-dev) material.
more in body
> -----Original Message-----
> From: [EMAIL PROTECTED]
> [mailto:[EMAIL PROTECTED]]On Behalf Of Ken Jenks
> Sent: Thursday, July 20, 2000 4:32 AM
> To: jBoss Developer
> Cc: [EMAIL PROTECTED]; [EMAIL PROTECTED]; [EMAIL PROTECTED]
> Subject: [jBoss-Dev] Hear ye, people interested in jBoss documentation!
>
>
> 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).
karect
>
> 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.
I don't know how feasable that is but we should try to run the following
examples.
1- we could do for sure at least Richard's book
2- Ed Roman's book as well, I know he will be happy to cross post
3- forthcoming stealth and secret Vlada Matena book (reviewing it)
Ken, let's take it offline and see how these dudes react to this.
> 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?
There should be an example in the books yes?
> 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,
Ok , that will take time but I think it falls on one of the developer's lap.
I will take it if no one else wants it.
> (2) an introduction to the jBoss architecture (with its plug-ins) and
> location of the javadoc HTML,
That's already there
> (3) a Web page for each jBoss development team showing team
> members, to-do
> lists, overviews like this one, etc.,
for the members the page is there already, but reserved for people that
contribute :)
The to-do per project should go in "status" on the current page.
I will put the web page in CVS right away so that project leads can access
it and update it. We will sync the CVS with the website.
> (4) a step-by-step tutorial on how to do a CVS checkout (for Windows and
> Unix),
yes, you can start with what is under "cvs" but it is not much
> (5) step-by-step instructions on how to edit, compile and test one class,
edit you can't really cover
compile is with the ANT (our standard make)
test, yes, for now the TestBeans, forthcoming JCTS
> (6) how to run the jBoss test suite,
> (7) how to check your changes back in to CVS.
Yes, limited crowd r/w passw only but helpful
> 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.
well it doesn't work to maintain a particular non portable make
ANT is our make and should be covered by default. Been there...
That being said I thought it was very helpful for some folks to have the
JBuilder how-to-debug-in thread here and that kind of knowledge can go in a
particular "how-to" format.
> 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?
It sounds good, but you know simple is good too, if someone can't click on
"get windows doco" or "get linux doco" in the first place, I am not sure we
want to be holding this dude around ... :)
kind regards
marc
>
> -- Ken Jenks, http://abiblion.com/
>
> Tools for reading.
>
>
