JBossDeveloper

 

"koen.aers@jboss.com" wrote:
Okay guys, I feel we cannot stay silent on this one. We know that the documentation is certainly not perfect, so your cricicism is valid. However, our resources are scarce and we have to make sure we evolve with our product to meet our customers needs. The balance between adding more function or more documentation is sometimes hard to find. While this may be a (bad?) excuse, it does of course not address your concerns...

I know there is pressure to add new features, but what good are they if they are difficult enough to use that you drive away customers through lack of documentation! As I said, I am a software developer. Writing doc is a pain in the butt, but I guarantee my users, and folllow-on developers have adequate instructions on my software before I release it. The whole point of my original frustrated post is, I think you are *way* off an adequate balance.

"koen.aers@jboss.com" wrote:
Anyway to be of a better service we really need your collaboration. One of the main ideas of open source software is that the community intrinsically provides the evaluation and test resources. So it would really help us if you point out your concrete issues where the documentation falls short. As the writers of the software, we do not know these issues automatically and hence do not always give the proper attention to some parts of the documentation. If you feel a certain portion of the documentation should be fixed, a section should be added in some place or a wiki page should be put up to perform some task, the best way to have the job eventually done is entering a JIRA issue (http://jira.jboss.com) stating the problem in the most concrete way possible. And of course you are also always welcome to put up the lacking documentation or wiki page yourself and help those who follow you to do their tasks more efficiently.

It is difficult to address specific concerns with the doc when there is simply not any there. Almost all the javadoc pages have the minimum generated by the javadoc command when no comments have been added.

Worse still, the user guide, which is shipped with version 3.0, and labelled JBoss jBPM 3.0 contains a tutorial in chapter 3 which shows code which will not even compile, because you moved the method. When you do that, you need to fix the tutorial, or stop shipping it. That doc is worse than useless, because it tells me to do something that will not work.

"koen.aers@jboss.com" wrote:
I am aware that this answer does not instantaneously solves your problems. Nevertheless I hope that you are not discouraged in using jBPM and are willing to collaborate with us to make things better.

Best regards,
Koen

You bet it does not solve my problem. I would love to spend a few months digging into your source code, figuring out what you intend and contributing stuff to you. Unfortunately, my employer is paying me to solve their problems, not yours.

 

"kukeltje" wrote:
I do not disagree, but do not agree either. The docs can be better (did you guys look at the docs in cvs or the ones on the site?) but are certainly not 'worse than useless'

I am using the documents that ship with the jbpm-starters-kit-3.0. They seem to be the same as the ones on the web site.

"kukeltje" wrote:
The first poster talks about simple things? What are they? It is hard for us to comment on these isues of we do not know what they are. Is the 'tutorial' to simple? Loading processes is also in the examples. So please provide us with the information on what 'simple things' are? We answer a lot of question quickly in this forum, so use that as well instead of just trying to find out on yourselves (although it is a good way to learn the details, but not needed in a lot of cases)

The simple thing was deploying a process programattically. The code in the tutorial is simply wrong, sonce the method it tells me to use no longer exists.

Part of the reason is the developer has restructured the code between releases 2 and 3. I started with 2.0, and had to move to 3.0 because of performance issues in the database code. I had a really hard time, since classes, methods, and even the philosophy of how jBPM works changed. For example, the doc on how to do unit tests in 2.0 showed how to move through a process one stage at a time, with the ability to examine the context at the end of each stage. With 3.0, signalling the process instance runs it all the way to the end, and all those tests failed, and had to be discarded. I still do not know how to make tests in 3.0 run that way.

It is fine to want to make the API perfect, but darn it, you published the API and you should feel some obligation to your users not the break all the code they ever wrote. If you need to move methods, a better approach would be to leave the original code in place, mark it @Deprecated, and put in a pointer to the method which replaces it. That way we have *some* hint what to do, rather than having to flail about blindly.

"kukeltje" wrote:
Lots of people think bpm is the ultimate solution for things. It isn't. In many cases more ui stuff is needed, like wizards, getting data from external systems etc... which is sometimes not easily done in a bpm engine (any bpm engine) and should sometimes just be done with more traditional pageflows (like jsf, struts). If you want to do everything in a bpm engine it has to contain so much (maybe even a kitchensink) that the core functionality gets to little attention.

I just want to code a fairly simple workflow that strings together several processing steps, kicks off on receipt of a JMS message, and has the ability to notify people when manual steps are needed. I would like to do it without having to read a ton of source code to figure out what to do. I read documentation, and do not mind javadoc at all. I just hate being misled by wrong documentation.

 

"kukeltje" wrote:
come on, lets all stay polite and not exaggerate. We do not play down your issues and please do not play down our efforts.

I am not trying to be impolite, and I do not think I am exaggerating. The "months" I was referring to was the time to learn the code well enough to write the javadoc and contribute it back. The developers who wrote the code could do it much faster, since they presumably know what the code is supposed to do, and why. The very fastest time to do it would be just after they finish the code.

"kukeltje" wrote:
It's true the code in the tutorial will not compile, point taken, but it has been asked and answered multiple times in this forum and the javadoc api (yes, without much additional comment) and the testcases show how it should be done. It would not take that long, certainly not months to figure that one out.

I found the answer in this very forum before I started this topic. I hate to ask questions that were already answered, so I searched first. It took about 10 minutes to get the right set of keywords to produce a small enough result set to make it worth looking at threads. This was after about 15 minutes of fruitlessly looking through the javadoc. Not a big deal in itself, but the cumulative frustration of several such occurrences lead me to post a complaint about the jBPM documentation.

"kukeltje" wrote:
Besides that, I politely asked all who agree with you to describe what their issues are. One did (PiN) and within a few minutes (ok 20) I gave him a suggestion and within the hour he was happy (see the posts in this topic). I'd be happy to help you out as well, but I do have to know your real issues (maybe they are problems but I cannot determine that).

My real issue is a general lack of, and incorrect documentation. There are about 180 classes in jBPM, and a very large number of methods. Do you really want me to open a problem report for each one that is not documented? I am not asking for a novel, and don't need or want a "how does this work" comment. I would like a sentence or two about "what is this for".

"kukeltje" wrote:
And last but not least, I do not even work for JBoss / jBPM and do this in my free time. It has probably taken me more time to read this post, reply, get frustrated, happy again because I helped someone and got frustrated again. Maybe not as frustrated as you are with the docs, but I LIKE TO HELP. without being payed by ANYONE

I do appreciate your doing this in your free time, and I am not complaining about you. You have answered questions for me in the past, and I am grateful. It would probably save you time and frustration if the documentation answered common questions once, rather than your having to do so multiple times.

 

"kukeltje" wrote:
You do not need to document all of the code in javadoc since that is only needed if you are doing extensive development on the core. Only a hand full of developers know their way and even adding javadoc would not mean a lot to people who have no graps of a framework for GOP (including myself).

Okay, maybe not all the classes, but how about the ones we really need to use to implement a workflow? For example, what are the methods in ProcessInstance for? Most of the method names are clear, but what about ProcessInstance.getInstances(). That looks like something I might want to use. Instances of what, though? It returns a Map. What are the key and value types? That is the level of detail I would like to see, at least for the classes we need to use and subclass to implement a workflow.

"kukeltje" wrote:
Maybe several people, including myself, should join forces and write a new, small, slim, but good enough tutorial/getting started.

I'll start a new thread on discussing this, so we can all get constructive. Agree?

That would be a good start. Another good idea would be a "Migrating from 2.0 to 3.0 Guide". That would have saved me a ton of time and frustration trying to figure out how to rewrite the code I had working in 2.0 before I migrated. Things like

Token.signal()

becoming

ProcessInstance.signal()

, and the fact I no longer needed to set a JbpmSessionFactory in the ProcessInstance. Also, the fact

ProcessInstance.signal()

causes the process to run to the end with no way to stop it in a test.

I would be willing to work on these, if you tell me how.