I’ve been working on a little pilot project using RIFE, spurred on by some of the glowing reports I’ve read of how productive it is, and I’m finding it a bit frustrating. Mostly it comes down to the documentation, or lack thereof.
What I want is fairly basic stuff: a web site where you can sign up as a member, and if you’re logged in, additional content appears on pages (e.g. a “log out” button) and you’re allowed to visit restricted-access pages.
I figured I’d start with the simple blog from the RIFE web site’s “theater” section. That went pretty smoothly and it all made sense; kudos to the RIFE guys on that. Then I started trying to extend it from there. I figured a good first step would be to add the notion of users.
The documentation describes how to set up authentication for a fixed, sysadmin-controlled list of users, “memory users” in RIFE lingo. That’s fine as a trivial example to demonstrate how to set up authentication elements and child triggers, so I’m not saying get rid of it… but I doubt there are very many site designrs who actually want that kind of authentication. As soon as I got the memory users working, the step I wanted to take next was to make RIFE read users from a database instead.
There is a section of the user’s guide that describes the element configuration to use database authentication, but that’s all it describes. Put that configuration in place, and then what? You have no users! What table does the authentication system use for user data, and what are its columns? How does one add or remove a user? Does the table have to be managed by the authentication classes, or can they use a user-supplied table that has other data about users than just their login names and passwords? Is it possible to store session data somewhere other than a database, e.g. in a clustered cache?
I downloaded the Elephant source, since I know it has a user database. (Elephant is a multiuser blog application written using RIFE.) Dug through its config files and found that its database authentication element is a little four-line class that extends a class called PurgingDatabaseAuthenticated. Great, I thought, I’ll just read the Javadocs on that class. Nope. The Javadocs don’t contain so much as a one-line summary of what the class is for, let alone a description of how to use it. Neither do the Javadocs for its superclass, or its super-superclass, or any of its ancestors until you get all the way up to Element, which is too general to have any bearing on the question. What is the “entrance” method that the Elephant authentication class implements? What inputs does it take, and what does it have to do? It’s a mystery.
One thing I did manage to crib from the Elephant source, a completely undocumented feature as far as I can tell, is how to use global cookies instead of URL decoration to keep track of the fact that I’m logged in. This is another thing that, I suspect, 99% of people are going to want to do. It shouldn’t be so obscure. In fact, in my opinion it should be what’s described first in the documentation, with the URL decoration method given as an alternative later on. I’d go edit the Wiki docs myself, but to be honest I am not confident I really understand it even though I have it working.
Query building is another area that seems a bit mysterious. What exactly do all those methods on the Select class do? (Not one of them has a description in the Javadoc, and only a couple of them are used in the examples in the other documentation.) What order can you use them in if you’re building a query dynamically?
Am I just missing the big picture here? It feels like in order to know how to use RIFE, you have to have been following the mailing list for long enough to have read all the design discussions for all the major features. I have so far spent about an hour looking for nonexistent documentation or examples for every ten minutes I’ve spent writing new code; if there is a huge productivity boost to be had from RIFE, I’m sure not seeing it yet.
Maybe part of my frustration is that I’ve been using the Spring framework; its developers seem to regard documentation as an integral aspect of coding. I don’t think I’ve ever seen them put out even a prerelease version of something that wasn’t pretty well-documented, though I’m sure others can point out counterexamples. But the point is, Spring feels like something its developers expect and intend other people to use. RIFE does not feel like that. It seems to view documentation (or, in other words, enabling people other than the author to use its features) as an afterthought at best, which to me is a big, big problem if it aims to be more than a tiny niche product. That’s a pretty harsh thing to say, maybe, but after working my way through the woefully outdated user’s manual (just compare how it tells you to do database access with what the blog demo tells you) and reading page after Javadoc page without any method descriptions, it’s a hard conclusion to escape.
As a new user I don’t mind learning what I need to learn, but I need there to be some way to learn what I need to learn, and I’m not really sure that’s the case with RIFE right now. The learning curve is far steeper than the framework’s complexity warrants. Which is a pity because I really do like some things about it, enough that I’ve been willing to keep plugging away when good sense tells me I’ve already wasted more time than it would have taken to do what I’m trying to do in some other environment.