[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [xmlblaster] UserGuide was: java.lang.NoClassDefFoundError: org/xmlBlaster/client/I_Callback



Salut Robert,

Dupuy, Robert wrote:
Michele,

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 ;)

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?
The xml format to write the requirements is very simple and nice to use but the drawbacks are:
- 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.


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.
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).


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.

Yes that is one other point. I must admit that I am having problems myself when I search for specific information on the requirements.

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.

So if I understood you correctly now you identified two different tasks:
- a restructuration of the requirements (lets say focused on the more experienced people)
- writing a tutorial book (from scratch).


Is this correct ?

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.

That is no problem. I believe we all don't know exactly where to begin. Important is 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.

Regards
Michele


-Robert


-----Original Message----- 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.

Salut

Michele



Heinrich Götzger wrote:

Robert,

On Tue, 25 Jan 2005, Dupuy, Robert wrote:



Quote:

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.


Greate idea.

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?

cheers

Heinrich