1 2 Previous Next 26 Replies Latest reply on Mar 30, 2006 3:21 PM by kbarfield

    The jBPM documentation is hideous

    jim.mcmaster

      My company is trying to use jBPM, and I wasting a terrific amount of time doing things that should be simple. The reason is, the jBPM documentation is worse than useless.

      For example, I tried to use the example code in the user guide to programatically deploy a process definition, to wit:

      ProcessDefinition processDefinition = JpdlXmlReader.parse(...);
      


      This does not even compile! There is no parse method, nor anything like it. After going to this forum and searching on several keywords, I found this functionality has become a static method in ProcessDefinition with a different name. It works now, but why did the tutorial lead me on the wrong track?

      I would have expected some help from the javadoc, but that apparently has never been written. There are method names, return types and parameter types, but nothing that gives me any hint as to what the methods might be used for other than their names.

      Development seems to be proceeding apace on 3.1, since an alpha is out. Do the developers ever intend to put a little effort into the documentation, so we mere mortals can reasonably use their hard work? I am a developer, myself, and know coding is more fun than writing doc, but at some point you have to do it. Otherwise, no one will take you seriously as an alternative. Friendly help from this forum is not a substitute.

      I would like to use jBPM, but will soon have to start answering questions about why things are taking so long, as I thrash blindly around in the source code trying to figure out how to do simple things. I would rather switch to a usable system than answer those questions.

        • 1. Re: The jBPM documentation is hideous

          Um - ditto.

          I am an Enterprise Services Architect and am on the cusp of writing jBPM into our SOA solution, but the developers who have been using it are all suffering a little. To find out what their grief is about I have been working through the product stack using the doco and now heartily agree with Jims comments.

          • 2. Re: The jBPM documentation is hideous

            yes i second that.
            i'm evaluating jBPM for a german bank and it is taking a huge amount of time.

            there are still docs for version 2.0 (like the getting started which uses the .parse method which doesn't exist anymore) which irritates the starters. maybe you could move them to another section rather than just printing "2.0" in a table row.

            • 3. Re: The jBPM documentation is hideous
              icyjamie

              There are already success stories of jBpm, and they all use the same resources and documentation. I personally use the sourcecode as the main documentation :-). I know this is not very user-friendly, but together with the concepts explained in the doc, we already got stuff working. Of course, the more you get involved in it, the better you grasp changes from version to version.

              If you want to use open source, think of the consequences in terms of:
              - support
              - documentation
              - SLA's
              - TCO
              - ROI
              If you can live with their constraints in terms of open source, go ahead and embrace the use of open source. If you can't, there are always the commercial solutions.

              In an open source community, one could stand up and say:
              "Hey guys, I see you can't cope with the documentation, let me do it", and contribute/update the docs, instead of using hideous subjects (pun intended :-))

              • 4. Re: The jBPM documentation is hideous
                koen.aers

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

                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

                • 5. Re: The jBPM documentation is hideous

                  you are right! that's why i suggested marking the old documents visibly as such. when i first started i used the wrong document...and bamm ;)

                  now i do it the way you do...look at the code + doc.
                  for me it is hard because i never used jboss, jsf, junit, ant...and every subject has it's own book ;)

                  it would be great i think if you could download the webapp seperatly without the blow of the jbpm project. so i can reflect the project structure with my project to get started...

                  the more i play with jbpm the more i like it and the forum's been a great help! so thanks!!

                  • 6. Re: The jBPM documentation is hideous
                    kukeltje

                    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'

                    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)

                    @n.belford:

                    Integrating it in a SOA (ESB?) is something that is indeed not covered yet. You'll have to use the low level api for sure. jBPM is btw not a product stack, it is a product in a stack (JEMS). I would not mind getting in touch with the developers (through this forum) and try to help out. If you could arrange that, lets see how quickly we can get things done

                    @PiN:

                    2.0 docs? Yes they are for version 2.0 of jBPM, but some people are still using it. Putting it in another section could be a solution for people how get confused by it. I'll forward this request.

                    In general:

                    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.

                    And now the ultimate request: If you guys have changes for the docs, mail them to me as a full page (no diffs) and I will make sure the changes get into cvs, but make sure the changes are against the head from cvs.

                    Since Philips changed there slogan, I dare to use their old one "let's make things better"

                    btw, thanks for reporting back. Success stories are always nice to hear, but we should and can take critique as well and do take it seriously.

                    Cheers,

                    Ronald
                    jBPM forum moderator

                    • 7. Re: The jBPM documentation is hideous
                      icyjamie

                      I only use the core and look at the tests to see how things are done (and co-writing them if I suspect bugs :-)). I'm not using jsf, controllers and the like. We like to use jBpm as our workflow engine, and integrate it into an existing application, for which we have already written a web frontend and a custom workflow backend.

                      • 8. Re: The jBPM documentation is hideous

                        when i started i just downloaded the "getting started" doc but oversaw the 2.0...what helped me a lot was the GDM doc with all those screenshots!

                        the thing was, after generating a processdefintion it is descriped how to write a junit test. and the tutorial stops there instead of step by step going through a simple app which starts an actual instance.

                        that said...now i realize it is all here...you just have to search and invest an amount of time!

                        the best thing actually is to look at the code. so maybe you can provide an eclipse project containing only the webapp. so beginners like me can reflect our own project's structure with the webapp...

                        thanks and keep up the good work!!




                        • 9. Re: The jBPM documentation is hideous
                          kukeltje

                          The last thing is exactly what I am doing in my private time and a little time from my daytime employer (not jBPM or JBoss).

                          There are some additions to the ui I'm working on that I want to show in a real world example. I do not have a (set of) unit tests yet for my process. Maybe this could be come a new 'getting started' or something, but you know.... time....

                          • 10. Re: The jBPM documentation is hideous

                            sounds great! but please don't stop at the point of unit testing. what i don't know is...what comes after testing and how do i really instantiate my deployed process via my jsf hello world...i'm still trying to extract that from the webapp examples...

                            so hopefully you find the time to write that stuff. i know it is very time consuming!!

                            thanks for your efforts

                            • 11. Re: The jBPM documentation is hideous
                              kukeltje

                              look at the HomeBean. It starts a process there, instantiates the 'start state task'

                              The HomeBean and TaskBean can provide a lot of insight. It certainly did for me.

                              • 12. Re: The jBPM documentation is hideous

                                hey thanks!!! this is the bean i was looking for but always overlooked...hopefully it will clear some things to me.

                                again thanks!

                                • 13. Re: The jBPM documentation is hideous
                                  kukeltje

                                   

                                  "PiN" wrote:
                                  that said...now i realize it is all here...you just have to search and invest an amount of time!


                                  Or ask ;-) .... (yes I know, a wiki entry would also be nice)

                                  • 14. Re: The jBPM documentation is hideous
                                    pksiv

                                     

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

                                    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



                                    Is there any documentation on what to expect in 3.1 ? A timeline, New Features etc... ?

                                    I have a problem I'm trying to solve and the answer I was given was more or less to use some new feature in 3.1. But without any knowledge of when this is expected to be production stable, I can't go down this path.

                                    1 2 Previous Next