Hi Geert,
Thanks for sharing your thoughts.
I must say that feel exactly the same way as Steven and most of the
time when I want to learn something new with RIFE, I end up reading
sources for hours.
It would be interesting to know which areas were the main problem for
you and why the current documentation didn't suffice.
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?
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.
2) Some best practices to save other people from making design
mistakes that have already been made. If I can find the time, I'd do
(1), but (2) is definitely something for some more experienced guys.
Hmm, honestly there are little things that I regret from my older
projects. Everything that I do differently now is because features
were contributed back into the framework to do the same things much
more easily (like constraints, continuations, pathinfo mapping,
annotations, ...). Conceptually-wise I still do a lot of the things I
did 3 years ago.
Hehe, I understand that very well. There was a point where I had pretty
wicked PHP mastery and wrote my own framework for this language. And if
somebody would have asked me about best practices for it back then, I
would have answered exactly what you just said. You have the complete
overview of RIFE. However, someone just learning it has a completely
different perspective, somewhat like this: I want to do something and I
know I could do it using method A or method B, but I don't know which
one is supported better in RIFE. Or maybe I might even miss out method C
that might be hidden in the framework somewhere.
Basically this problem just means that I have little experience with the
framework and no amount of documentation can magically change that. But
there are a few things that might help. There are a few undocumented
features in the framework (at least the scheduler was one). These should
be tackled with priority, even if they seem useful only for a small
amount of users. The second thing is, that while I like both the
tutorial and the cookbook format, both are very problem-oriented
approaches, i.e. "How do I do X?", the bottom-up perspective. What I'm
missing is more structured information that is concept-oriented, i.e.
"What areas can RIFE functionality be divided in? What are the concepts
behind?", the top-down perspective. The first one is needed to get
simple things done fast. The latter is needed to expand upon what RIFE
can do today. My hope is that your upcoming books will fill this gap.
(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.
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.
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.)
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.
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." ;)
Cheers
Stefan :)
*) This is not a job for the RIFE gurus. This is something everyone can
contribute. See my call to action at the end of this mail. :)
Geert Bevin schrieb:
Hi Steven,
I'm sorry that you're bumping into this block.
I agree that documentation is lacking in some areas, mostly for code
that was initiated earlier than three years ago. We've tried to fill
in the Javadocs holes and I think that in the areas that we did
cover, we're doing an excellent job at this. In contrast to what
you're saying, there have been many compliments about the quality of
the current documentation (even though there are lacunas). Also,
since three years, no public APIs get committed anymore without
Javadocs. Additionally, as you probably saw, each release contains
extremely detailed release notes with examples that are afterwards
aggregated in the wiki's cookbook. I think that there is no
open-source project out there that does this as extensively. Stating
that documentation is an afterthought thus feels really very harsh
to me. A project with the momentum of Spring, with their amount of
contributors and commercial companies behind it, is of course able
to provide a lot more in terms of books and user guides. There's
only so much that a small team of motivated developers can do for
free in their spare time. However, if you do feel that some areas
need to be improved quicker, you're always welcome to contribute to
the effort and document your findings either in articles or Javadoc
additions that you can send to me as patches.
I'm working on a series of three short books for O'Reilly though, so
soon there will be a source with more centralized information.
You're right that database authentication isn't documented in detail
and it really needs to receive some love since imho it's *the* area
that is the most confusing to people. I think that you can find what
you need here though:
http://thread.gmane.org/gmane.comp.java.rife.user/2767/focus=2767
Other posts on the mailing list cover this too. You don't really
have to be following the list for a long time, since a simple search
should reveal all the posts that are relevant to you.
With regards to the query building, the methods of the Select class
are mostly the same as the SQL methods and should need little
documentation if you know SQL. I agree though that there should be
Javadocs there. It's one of the missing parts of early code that
never received the documentation care that it deserves.
One of the points of the query builders is that the order is not
fixed at all. The real statements are only created when the SQL is
obtained from the builder manually, or when it's executed. This also
means that you can partial query builder objects that you prepare in
one location of your code and complete elsewhere.
I hope this information lets you climb out of the dip you're in and
get back up to speed. Otherwise, feel free to mail the list with any
additional questions you have, you'll see that a lot of people here
are very helpful.
Best regards,
Geert
On 18 Jun 2006, at 10:20, Steven Grimm wrote:
I feel like I'm fumbling around in the dark with RIFE. How are
other people coming up to speed on this framework? I'm finding
myself spending five times as long searching (often fruitlessly)
for documentation as I'm spending actually getting work done. (It's
the "fruitlessly" part that really irks me.) Right now my bugaboo
is database authentication; there seems to be very little
documentation on how it actually works in practice, just an example
element configuration in the user's guide.
I've written a blog entry on my experience so far:
http://www.plaintivemewling.com/articles/rife-with-frustration
Hopefully nothing too unwarranted there; sorry if it raises
anyone's hackles, but I'm not a very happy RIFE camper at the moment.
--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
_______________________________________________
Rife-users mailing list
[email protected]
http://lists.uwyn.com/mailman/listinfo/rife-users
--
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
_______________________________________________
Rife-users mailing list
[email protected]
http://lists.uwyn.com/mailman/listinfo/rife-users
