Hi Stefan,
Hmm, one example was, when I tried to send an email and I
remembered RIFE had some functionality for this. After reading
through the examples and looking at the code, I realized that RIFE
only supported asynchronous sending of mails. Probably because
synchronously sending mails was considered trivial. Still took me a
while to figure it out. Not really a problem with the documentation
though. What we need is a more structured approach, so you can go
look at "RIFE > Mail" and if it's not there, it's not supported.
Right now the only sure way is to use the search function of the
Wiki. But what if you don't know the proper keywords?
Actually, I'm still planning of adding a "send" method to the
MailQueueManager interface to send emails immediately. ;-)
Most features are somewhere. True. But ideally they should be
documented everywhere. How to do user authentication should be
discussed in the tutorial, but it should also be in the Cookbook
with all variants. *)
1) A complete syntax manual for all XML config files and
Are you mainly talking about the site and the element files here?
Normally the concepts of those are documented in the (old) users
guide and the cookbook.
Yes, but a tutorial is hard to use as a reference to look things
up. The features of the site definition are all over the place,
introduced one at a time throughout the tutorial. This is good when
you first learn it, but extremely annoying, when you want to
revisit something or try something that just doesn't happen in the
tutorial. But don't bother, I'll condense the stuff and write
something in the Wiki soon.
I agree, and thanks for planning on contributing!
I'm writing my books as a reference manual instead of a tutorial, so
there might be something useful in there too.
The latter is needed to expand upon what RIFE can do today. My hope
is that your upcoming books will fill this gap.
That is the plan ;-)
(Please note that while the JavaDocs are by principle concept-
oriented, they are more meant to look something up than to
methodically learn something.)
o------------------o--------------------------------o
| Methodical | Reference |
o-----------o------------------o--------------------------------o
| Bottom-Up | Live Users Guide | Cookbook/Mailing List Archive |
o-----------o------------------o--------------------------------o
| Top-Down | ??? | JavaDoc |
o-----------o------------------o--------------------------------o
But that's just how I see it. Hope it helps.
Very nice diagram and overview of how the documentation should be
structured. Thanks a lot!
Another thing that comes to my mind is: Geert, could you recommend
some non-RIFE-related reading that might help with the big picture?
Maybe some books or articles about this whole concept of web data
flow/web logic flow. Or about component-based framework in general.
I feel like I'm lacking some of the basics and while it's not your
job to explain this stuff to people you might be able to point them
to valuable resources.
Sadly I'm not really aware of any reading material like this. RIFE's
model really grew out of real-world problems that I had 5 years ago
and it has been enhanced over the years. Nowadays though, it's nice
to see other solutions pop up that adopt some of the same concepts.
At least it validates the approach and allows for a common
nomenclature to be used. I never read a book about them though.
There are some more points I really want to emphasize:
1) There's nothing "wrong" with the documentation. I like it and
that learning RIFE takes a bit of time is just a logical
consequence of it's sheer size and power. (Not to mention the fact
that it is some of the most advanced technology on earth today. I
mean, how easy can it be to learn it? If you want an easy way to
create simple web sites, there are better tools out there. Tools
like RIFE are meant to help you writing web-applications of a
complexity that would just not be manageable without them. As a
side effect, you can also become more sovereign in writing simpler
apps.)
However, I think it's important to continuously strive for the
initial learning curve to become lower all the time. RIFE has a lot
to offer for the simple projects too. One of the key areas here is to
reduce the declaration and configuration overhead. I think that
annotations (for RIFE 1.5) and RIFE/Crud are doing a lot for that
already.
2) What the documentation needs is more perspectives. So I
encourage everyone currently learning RIFE to just go for it,
create pages in the wiki, talk about what you're doing. If you're
writing something dumb, others can correct it. Also, don't hesitate
to change existing documentation in the Wiki to clarify it. The
only way to make RIFE easier for a wide audience is to have the
docs written by a wide audience. It can't hurt, it's a Wiki goddammit.
Wonderful :-) Woohoo, exactly. People, this is the purpose of the
wiki. CONTRIBUTE! Write anything about that you found interesting or
that you had a problem with. Correct stuff from others, or comment on
them, etc etc.
Damn, I think I have to set a good example. I'll go forth and write
a few things in the next days. And, just for the protocol: I
really, really, really don't have the time to do this, but I'm
gonna do it anyway. So guys, don't rationalize your shyness to
contribute with "I don't have time to do this." ;)
Welcome to the club! I'll tell my girlfriend that there's one more
like this out there now, working on borrowed time ;-)
Take care,
Geert
--
Geert Bevin
Uwyn "Use what you need" - http://uwyn.com
RIFE Java application framework - http://rifers.org
Music and words - http://gbevin.com
_______________________________________________
Rife-users mailing list
[email protected]
http://lists.uwyn.com/mailman/listinfo/rife-users
