[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [xmlblaster] UserGuide was: java.lang.NoClassDefFoundError: org/xmlBlaster/client/I_Callback
Dupuy, Robert wrote:
Well said I would wait to later, but there is so much activity on the list, I don't want to stop the conversation!
Well, yes, I want to help, of course, I do not know the xmlblaster team very well now...but then again, what better way to get to know people :-)
We are all nice people of course ;)
The xml format to write the requirements is very simple and nice to use
but the drawbacks are:
You mentioned a project about converting the existing requirements to docbook format. I admit I am ignorant about the history of xmlblaster (I guess this is an attempt to learn that now).
So, it seems to me that you have a specific need to convert existing documentation to a new format, with the old format represented by the requirements pages which can be viewed on xmlblaster.org, and the new format being in docbook format. Is this a correct assessment?
- it is proprietary
- it embeds some pure html tags (this is possible since it is not validated)
So it would be nice to switch to docbook since a lot of people are using
it and since you can generate the documentation on different formats.
That is exactly the point. I believe we all are very aware of the fact
that there is exactly the need of such a tutorial documentation. As you
say it, the requirements are a good (and in some cases the only place)
to search the information. They are normally uptodate and are really the
"reference" (if something does not behave like described in the req.,
then it is a bug).
I think then, that reference documentation is one project that the xmlblaster.org team has already identified, and addressed.
Then, there is another type of documentation a tutorial style, which I would suggest is a good idea, and I know that you probably don't have time to do that, given that you mentioned the docbook project has been on hold due to lack of time.
Yes that is one other point. I must admit that I am having problems
myself when I search for specific information on the requirements.
But I volunteer to help. I know, anyone can write a book if they want, but it would be very neat to work with the xmlBlaster team...I would find that personally satisfying. Anyway, coming from the publishing business, I know that each document has an intended audience, my personal experience with the documentation on xmlblaster.org, feels like it is in a reference style and aimed at the experienced java developer, and its somewhat disjointed, as most xml generated docs tend to be.
So if I understood you correctly now you identified two different tasks:
A more tutorial style 'book' (oh I don't know, even DOS for Dummies style)...would probably be beneficial to the project, if it existed.
Anyway, these are my beginning thoughts, which is there are really two separate tasks in need of addressing.
- a restructuration of the requirements (lets say focused on the more
- writing a tutorial book (from scratch).
Is this correct ?
That is no problem. I believe we all don't know exactly where to begin.
Important is to begin ....
Also, on a personal note, this would be my first attempt to help on any open source project, so please forgive me if I don't know exactly where to begin.
By the way, I believe the in the job of writing a tutorial it is often
of no benefit of being an "experienced user". Beginners are often more
suited to identify the weakness of a documentation.
From: owner-xmlblaster at server.xmlBlaster.org [mailto:owner-xmlblaster at server.xmlBlaster.org] On Behalf Of Michele
Sent: Tuesday, January 25, 2005 10:37 AM
To: xmlblaster at server.xmlBlaster.org
Subject: Re: [xmlblaster] UserGuide was: java.lang.NoClassDefFoundError: org/xmlBlaster/client/I_Callback
My personal opinion is to start it already from the beginning in
docbook. In fact one of the other topics on our long nice TODO list is
the face-lifting of the xmlBlaster homepage.
This work has been started but is currently "put on hold" due to other
priorities. We use forrest and the new requirements will be written in
docbook (docbook 4.2). The status is such that we already have an xsl
converting our exisiting requirements to docbook.
I was not really enjoying my first steps in docbook but I now got used
to it and I started using it even for other documentation.
*Robert, I am really happy of hearing you are willing to contribute.* Of
course if you have some ideas, both on the content and structure of such
a guide and on the tecniques to be used let us know.
Heinrich Götzger wrote:
On Tue, 25 Jan 2005, Dupuy, Robert wrote:
You can not immagine how difficult it is to
find somebody willing to do that job :(
You know I'm using xmlblaster now, I use it as an error message bus,
which is why I need to support various clients, like vbscript, vba,
vb.net, c#.net, and java (so far, those are the only clients I
need)...actually, in all cases I use the xmlrpc libraries, because as
you all know from my many e-mails, I cannot get the activex bridge
working, and...having some problems similar to nelson with the java
client. I need to put my java client inside the internal oracle jvm,
and it is amazingly difficult to put the whole thing in there...a
slimmed down java client would be much easier to load into the
internal jvm, with all its various issues...
Anyway....as far as writing a user document goes...I wish to
contribute to your project, so, I've decided to come out of the blue
and volunteer to do that...I don't know, maybe it's a large project
for one person, but I could get it started.
So how would we start this, I could think about a closed-wiki to start
collecting paragraphs and chapters.
Once we have some finally looking structure we could think about
something like docbook or so.
What do you think?