Ein wunderschoenen Guten Tag! (Have a wonderful day!)
As requested by Marc and promised earlier by me I want to inform this
list about the progress the jboss-docs list did in the last days.
This is our plan:
1) discuss and decide which docu types should survive : mainly discussed
and documented
2) discuss and decide which format will be used: *now active*
3) prioritize tasks and decide if any very important docu is missing
4) assign docu writing, integrating and converting tasks.
5) do it!
6) See JBoss surpass Weblogic on the next review, as the docu should no
longer be a problem ;-)
So far Michel de Groot assembled a summary, thanks! Here are the parts
which capture the result of the discussion up to now:
-----
JBoss user documentation
Summary
This document provides common terminology to prevent confusion. It
presents the basic structure of JBoss documentation. It defines the
tools & technology to be used for JBoss documentation.
Intention
To summarize what has been discussed on JBoss-docs so that the
JBoss-docs group can advance the discussion.
Scope
This document applies to all user documentation to be written for JBoss.
It does not cover developer documentation.
1. Definition of terms
Q&A (Question/Answer)
Definition: A short explanation of the user's question that points to
more elaborate documentation.
Elaboration: The Q&A reiterates the question of the user in such a way
that the user is sure that this Q&A is indeed about his question. The
Q&A provides a brief answer to the user's question, and/or points to
more documentation on the subject in for example the Manual.
FAQ (Frequently Asked Questions)
Definition: A document containing a combined set of Q&As.
Elaboration: The FAQ contains many Q&As. These Q&As represent the most
often asked questions.
1) As a rule of thumb the most frequently AND the most important
questions new users have go into the FAQ.
2) Really short answers and short summaries may go into the FAQ. All
more extensive docu goes to the manual. Each answer may have additional
pointers to more detailed sections in the docu.
3) The FAQ is a part of the manual itself. This is possible since we
will probably have a HTML version of the manual. On the docu page on
www.jboss.org we could have a link that directly leads to the HTMLed FAQ
section of the manual.
User's Summary
Definition: A short explanation what JBoss is.
Elaboration: The User's Summary must make clear to the user in a short
time whether JBoss can help in solving his problem or not. It tells
what it can do for the user. Also, it explains what JBoss cannot do but
is often expected to be capable of. Contains a section 'Expected in the
next milestone release' which briefly lists those issues that are being
worked on by JBoss developers and points to the Roadmap. User's Summary
contains a summary of the License and the complete License.
Manual
Definition: The detailed use specification of JBoss.
Elaboration: The Manual describes how JBoss can be configured,
integrated and programmed and how JBoss reacts.
Quick Start
Definition: Detailed and bullet proof step-by-step instructions for
installing and running a sample application with JBoss out-of-the-box.
Elaboration: The Quick Start helps the user to install and run JBoss for
the first time. Therefor, it should be bullet proof and simple. There
must be no cause for errors. The user should not have to leave this
document in order to get the sample application running on his system.
Quick Start does not explain how or why, but does provide a small amount
of pointers into the Tutorial.
Tutorial
Definition: A step-by-step description of how to make a standard
application.
Elaboration: The Tutorial is intended to get the user developing on
JBoss. It does so by providing a step-by-step description of the
development of a standard application with only basic features and no
options or advanced features.
Error
Definition: Identical to a Q&A, but the Q is about an error that the
user experiences in using JBoss.
Elaboration: Errors can significantly delay development and are often
hard to track down if unexperienced. The Error provides a short answer
which must point the user in the right direction to solve the error. The
A of an Error can be more elaborate then the A of an Q&A.
Roadmap
Definition: Defines what and when will be delivered in the future.
Elaboration: The Roadmap provides with an idea where JBoss is heading
and when it is there. We cannot however provide hard deadlines and/or
guarantees.
2. The Goal of the JBoss user documentation
To provide first class documentation for users that explains how to use
JBoss for their various purposes and in their various environments so
that JBoss is recognized as a top-tier application server. JBoss
documentation strives to be up-to-date with current binary releases.
The JBoss community is a large group of mostly volunteers working
part-time on JBoss. The Internet is used as the common communication
medium. Users can be found world-wide and are using a wide variety of
software.
To reach this goal the following requirements must be met:
a) Complete, verified, consistent and up-to-date with the last milestone
release.
b) Suitable for editing and reading on many different platforms.
c) Suitable for distribution over the Internet.
d) Suitable for use in off-line digital, on-line digital for low- and
high-bandwidth Internet connections and paper formats .
e) Suitable for distributed, parallel writing.
f) Low entry level for participation.
If different JBoss releases are not compatible, sections concerning
those incompatibilities are preserved for all different versions.
3. Structure of JBoss documentation
The structure of the JBoss documentation helps to make it complete and
consistent. Also, by structuring the documentation it becomes possible
to work with many people on it without loosing quality.
a) Top level
At the top level, JBoss documentation contains these major documents in
the mentioned order:
1. User's Summary
2. Quick Start
3. Tutorial
4. Manual
5. FAQ
6. Roadmap
7. Miscellaneous - contains contact information, URLs etc
The Manual, Roadmap and the FAQ are presented in more detail in chapters
5,6 and 7.
4. Tools & technology
* in discussion right now *
5. Manual
The Manual is divided into a number of chapters. Each chapter covers one
J2EE topic, like JSP, EJB, JMX, JMS etc. The Manual is not a J2EE
handbook and does not explain J2EE in detail. Rather, the Manual covers
these topics from the perspective of JBoss. The Manual also contains
separate chapters about integration and configuration issues if these
are sufficiently large.
Each chapter starts with a general overview of the topic explaining what
can be done with it and where more J2EE information can be found.
The chapter then continues with subtopics covering a specific area of
interest. These subtopics are described in detail. The structure is such
that the user can perform the trick step by step himself. Sample code
and config snippets are provided where possible. The examples must
assume the default installation of JBoss, so that it is reproducible.
Subtopics must be self-contained if possible and not refer to topics
still to be covered in later subtopics. Therefor, basic subtopics can be
found early in the manual, while complex subtopics can be found later in
the manual.
Current list of subtopics in order:
+ Installation
+ Configuartion
++ Basic (you should be ready to start the server afterwards)
++ Advanced (extending the predefined datasources, Security, Logging
etc.)
+ Managing JBoss
++ start/stop
++ webinterface/jmx
+ Writing software for JBoss
++ beans
+++ EJX
+++ deploying
++ clients
+ Third-Party Products
++ j2ee
+++ tomcat
+++ jetty
++ persistence
+++ cocobase
+++ ozone
+++ castor
++ IDE
+++ kawa
+++ Jbuilder
+++ VisualAge etc.
+ J2EE topics
++ JSP
++ EJB 1.1
++ JMX
++ JMS
6. Roadmap
The Roadmap lists which enhancements will be ready in what release. It
also lists when the milestone releases are expected.
The chapter is divided in sections, each section covering a milestone
release. The milestones releases are listed in increasing order.
7. FAQ
The FAQ is divided into two parts in this order:
a) Q&As
b) Errors
Each of these two subsections is divided into major subjects (to be
determined). Under each of the major subjects many Q&As or Errors are
listed, all related to the same subject.
-----
I hope that's good enough for the moment. Otherwise I might loose my
head to Marc ?
Cheers,
Tobias
