Tuesday, December 16, 2008

NON-Documentation

Greetings:

Did you ever download a software package and start reading the Readme.txt or ReadMeFirst.html file to see how to install everything and then find out that it had not been changed recently? Or that you downloaded the Mac OS X version, installed the Mac OS X version only to find out that all of the instructions were for either Windows or Linux? OK, so Linux should be close, right? If it works, yes. If it doesn't work, wrong!

I just downloaded ILOG JRules Studio 6.7.2 Evaluation package. The instructions clearly state
=======================
To run Rule Studio do one of the following:

In Windows, use the shortcut: Start > All Programs > ILOG > ILOG JRules > ILOG Rule Studio for Java.
On Linux, start Eclipse using the executable in /studio
=======================

Nope. Not on Mac. There are some .app files there but they don't run on the Mac - maybe on Solaris or Linux, I wouldn't know since I usually do everything on a Mac or, sometimes, Windows. So, you have to find the build.xml file, read through it, and see if you can modify it so that you can make it run on the Mac properly.

And, remember all of those older files that you had to run under JRules? Forget it. You may as well rewrite all of that stuff using the "New and Improved" Eclipse interface. (Personally, I like writing my rules with a text editor but even the old BAL was kind of nice.)

Have you read through the Drools documentation recently? I really like Mark Proctor, Edson Terelli and the rest of the Drools guys - and I like the product - but they write what HAS to be the worst documentation in the industry. BUT, now that they are moving into "Big Boy" territory of BRMS tools (Advisor, jRules, etc.) Red Hat needs to hire a team of "real" Technical Writers to come in and help with writing proper documentation. I certainly hope that they do something soon or the only people using Drools will be the ones who can use the rulebase engine only and forget any of the ancillary bells and whistles that they have spent the past eight to twelve months adding to Drools.

I guess that the best documentation that I have seen is (forgive me for plugging an ex-employer) is the Fair Isaac stuff. Good docs that (usually) agree with the current version and is easy to use. Visual Rules docs are probably a close second. I've never had the privilege of using Haley Expert Rules so I can't say about them. I did look at Haley Office Rules but wasn't overly impressed with their documentation. ILOG JRules (the purchased version) documents used to be on a par with FIC but recently they have tried to go the "El Cheapo" route and skimp on that end of the product.

Anyway, before you DO happen to download the Studio, go to the chat room and see all of the problems that they are having with this "freebie" that they are putting out for six-month evaluation. THEN, if you still want it, at least you have been forewarned.

SDG
jco

9 comments:

Anonymous said...

Jim,

JRules 6.7.x does not officially support Mac OS X, so you can't really blame the documentation!

Because I'm a nice guy (!) I wrote this a while back though:
http://blogs.ilog.com/brms/2008/06/20/installing-jrules-671-on-mac-os-x/

Sincerely,
Dan

James Owen said...

Daniel, mon cher petit! :-)

Greetings:

You are correct, sir, in that you did indeed post the method of running JRules under 6.7.x BUT this is not included in the downloaded documentation anywhere. Not even the link to your invaluable information.

Also, the downloaded version was, like, 700MB and still did not include WHICH version of Eclipse nor that you needed specific versions of EMF, GEF and BIRT or the stupid installer would not recognize a later version. EVEN THOUGH the instructions (as you were installing) said "version x or later."

And you are a nice guy, even if you are are galvanized Brit living in France. (Yes, I'm just jealous.)

SDG
jco

Anonymous said...

James,

I can respect your opinion about the JRules documentation, but in fairness to the fine people who write it for us, I feel obligated to point out the following text from the JRules 6.7 readme:

Start Quote

Supported Rule Studio Platforms

* Eclipse 3.3 + GEF 3.3 + EMF 2.3 + BIRT 2.2 + DTP 1.5

GEF stands for Graphical Editing Framework
EMF stands for Eclipse Modeling Framework
BIRT stands for Business Intelligence and Reporting Tools
DTP stands for Data Tools

...

Rule Studio is not supported on Mac.

End Quote

Pretty clear to me.

Steve
(Director of Product Management at ILOG)

James Owen said...
This comment has been removed by the author.
James Owen said...

Daniel and Steve:

"In all fairness" that information is contained in the "readme.html" document that is only viewable AFTER you have installed the product.

Daniel's blog should be updated (since you no longer have to move it to the Applications folder on Mac) and the readme.html file should be viewable BEFORE you install the product.

Also, the documentation leaves off the final digit on the installation. I used the "right" according to Daniel's blog and it STILL complained during the installation that it was not the right version.

I realize that Mac is not a "supported" platform but you could at least have a download link with the complete listing of required products BEFORE installing. I just spent an entire day doing this and re-doing because I "thought" that I had made a mistake when I hadn't.

And the fine folks could include some decent PDF documents rather than HTML for those of us who like the "bookish" approach to reading documents. I have discussed this innumerable times with you predecessors and they assured me that this would be corrected. Apparently they left before they could complete it.

SDG
jco

SDG
jco

Anonymous said...

James,

Agreed we should provide access to some sort of readme and thus the supported platforms prior to putting you through a 700Mb download. I'll take that suggestion as a constructive criticism and get it fixed.

But let's really be fair with each other - when you went to get the download, you were offered two installers - one for Windows, one for Unix. There was no Mac OS X installer such as you mention. You were nonetheless able to download and run the Unix installer - OS X being a Unix derivative - and get to the readme. You didn't read the readme as your post describes however, since we know it clearly says the Mac is not a supported platform for Rule Studio.

Now, I'm perfectly happy to have informed and reasoned criticism of our product - it's not perfect, but we go ahead and make the 6 month trial freely available anyway, essentially inviting people to discover both our strengths and weaknesses. So, I'll work on your suggestion about making the readme available pre-download. But overall, I'm rather proud of the work our doc team does, and would hope criticism of their work reflects that work a bit more than what I see here.

James Owen said...

Greetings to all ILOG Product Managers, Documentation Managers, Engineering Managers and any other manager who was offended by my posting on this blog:

What part of "Free Berkley Systems Division UNIX and X11 Windows" do we not understand here? NOT supporting the Max OS X platform is the same as NOT supporting Free BSD Unix. U-N-I-X !!

"To be fair" several other manufactures do not openly support Mac OS X either, which is strange since they support Solaris x86, Sun's version of Unix for the Intel platform. But it runs fine on the Mac anyway. (Blaze Advisor, CLIPS, Jess, Drools, etc.) And they support Linux, which is not Unix at all but a hybrid that has Unix commands but it is NOT Unix, it is Linux.

Free BSD had been here since about the time of SCO Xenix (or before?) and to NOT support Free BSD and X11 windowing is tantamount to supporting "some Unix implementations" but not all. To me, Mac just put a pretty face on Unix. Unix has always been 32-bit, multi-tasking, multi-user and networking was something that was an integral part of the OS. Xenix was 16-bit and then 32-bit. Windows was 16-bit (and only much later 32-bit) SINGLE USER OS that "evloved" into a multi-user system through lots and lots of overhead.

So, "in all fairness", give me a break. I've been working with computers since 1962, before most you guys were born. I would wager not many (any?) of your engineers have ever done analog computer work nor actually built a computer (not assembled, built!) by hand. Not many have actually Machine Language nor Assembly either.

I've been doing PC's since about 1982. I've been doing Unix since about 1985 when Xenix hit the market and I could afford it. Now that it's more readily affordable, I "try" to use nothing but Unix. But, because I review vendors who are Windows only, I HAVE to have one or two around just for that purpose.

When I buy a Windoze machine I spend at least a day upgrading it to the latest and greatest. The Mac comes "off the shelf" fully loaded and ready to run. And it comes with most of the tools that I need to do productive programming.

Again, "in all fairness," the client market is probably about 90% Windows, 5% Linux and 5% Mac. But of the three, Mac is far superior. The server market is dominated by "real" Unix (UNIX) - by Sun and AIX (now that HP, SGI, DEC and others have been absorbed and forgotten) but Mac Servers are available "off the shelf" with 8 CPU configuration.

And, yes I am a Windoze bigot. I supported Minix and Linux when we (the poor, the down-trodden, the suffering geeks) could not afford the good stuff from Sun, IBM, DEC or HP. But now Mac has give Unix a new life.

BTW, I just picked up another Windows machine. It's a Quad-core with 64-bit Vista. But, it turns out, that ILOG BR Studio doesn't support that either. Weird. So I'll have to run everything on an older machine and upgrade it to more RAM and HD to do anything constructive.

FINALLY, I really like the JRules product. JRules has supported my family for many years, beginning with version 3.0. But you guys need to fix the documents and get it running on 64-bit machines. BTW, you might also check into parallel rulebases while you're at it - Dr. Forgy gave a talk on this at ORF 2008. It's only been around since the mid to late 1980's. :-)

SDG
jco

woolfel said...

Having read through blaze 6 docs and JRules 6 docs, I have to say my personal preference is JRules. The examples provided by jrules are much better than blaze. On many levels, JRules is a superior product. One simple example is the decision tables in blaze. It is based on applets and doesn't even let you sort or filter the rows. A half way decent swing developer can easily implement a better decision table that supports sorting and filtering. the rule flow editor in blaze is also user unfriendly. FI needs to dump all that stuff and start over with eclipse as the foundation. This way, developers can easily deploy the application to the server and take advantage of all the existing plugins out there.

The design of blaze rule repository is also flawed. The versioning is at the ruleset level, rather than the rule level. The reporting and auditing capabilities of blaze repository is sadly lacking.

In my mind no single commercial or open source rule repository meets the requirements I've had over the last 8 years. All of them could improve. A simple thing like allowing multiple rulesets share rules is critical to building maintainable large scale applications, yet all of the products on the market do not support it.

Atleast with jrules repository, you can include several rulesets in a rule application, so it makes it easier to reuse rules. It still isn't as flexible as allowing rulesets to share rules, but better than nothing.

Also, jrules rule scenario server is much better than anything else out there. It's far from being complete, but it's definitely more than other products.

from my own experience writing rule repositories and natural language rule editors, current products still have a lot of room for improvement.

James Owen said...

Peter:

Nice to hear from you. :-) While we might disagree on which BRMS is the best, I still like CLIPS for C/C++ and OPSJ for Java. Right now I'm looking at VisiRules for Prolog backward chaining and, so far, it looks really good.

However, I have to point out that my problems with JRules was NOT the product but the documentation. "In all fairness," JRules has supported me for a long time - ever since about 2000, to be exact and I really DO like the product itself.

I may not agree with all of your comments about Blaze Advisor but we can chat about that later. And, just for the record, most rulebased systems do not allow for rule versioning, just ruleset versioning at best - if that. And usually it's because they incorporate CVS or some other 3rd party product.

Returning to my blog, the blog was about the documentation - it is HTML only and, IMHO, it is NOT laid out very well. I much prefer the professionalism of the Advisor documentation.

Now, what you, my fine feathered friend, need to do is open up your blog to the general public and allow anonymous comments. The last time I looked anyone who wanted to read your blog had to be an approved reader. Open UP! Share your thoughts on your blog with everyone and let them take their best shot. I imagine that the Advisor folks will like to comment on your comments so why not drop by the Expert Systems Consulting blog, http://ExSCG.blogspot.com is the site, sign up as a blogger (you were an invited blogger some time ago) and republish what you said here for everyone else. :-)

Again, thanks for dropping by. And I would like to see your comments on the ExSCG.

SDG
jco