Thanks for the response -- comments inline.
[EMAIL PROTECTED] wrote:
Richard Feit wrote:
It's great to see some JPF docs getting off the ground -- we're sorely
lacking here. And it's nice to see a different (and logical)
perspective on the technology. What's the easiest way to get detailed
feedback to you?
You can email me directly ([EMAIL PROTECTED]), you can IM me (Eddie can give
you my IM), you can ring my phone (likewise, talk to Eddie), or in a day
or so, I'll get'em to Steve Hansen so they can get into the repository
where you can edit them directly. I don't have commit privs, so once
I toss'em over the wall to Steve, I'll have to submit diffs/patches,
so just trying to polish them up as much as possible before then.
OK, I'll try to get this to you tomorrow.
Also, I was starting wiki sections on Page Flow
features, tech details, and relationship to struts. I think there may
be some overlap between the first one and the overview you're
developing. Do you see the overview as expanding to drill into the
range of features, or would the scope be roughly equivalent to what it
is now (+ patterns, + annotations)? Either's fine -- I see this and the
wiki pages as complementary.
My view on Wikis, which many might argue with, is that they are a great
place for farm content, but then we should harvest it into the site's
static pages. Exceptions would be the 'patterns' page, since that's
a potentially unbounded set of content, with other contributing over
time. But things with a bounded set of content (ie, basic user guides,
feature lists, etc) tend to be better received when part of the core
set of documents.
I actually agree with this. I was wondering whether you felt that what
I was writing (regardless of where it ended up) would overlap with what
you're writing, but I think you've addressed this below.
It sounds like the pages you're working on in the wiki might should be
part of the xdoc/forrest pages, but not necessarily a part of the ones
I plopped up. The use-case, if you will, that drove my docs was the fact
that I've had a lot of people asking "what are pageflows? why should I care?"
and I wanted to provide a clear way for them to progressively evaluate
the technology from general concepts down to the hoops'n'hurdles of
actually using it.
I agree for the most part, except that I think an overview should at
least mention some of the major features (e.g., declarative exception
handling, nested page flows, declarative form field validation, etc.),
if only to whet the appetite. It might be a sentence or two that frames
the feature set. To me, this seems to be part of the "why should I
care?" aspect. Another set of docs could drill deeper into the
features, and yet another could do a technical look behind the scenes.
The technical details are important to have, and represent another
form of evaluation that may occurr. Once they've answered the
"why should we care?" question, then I see that information being
part of their due dilligence that is a part of any technology
selection.
I noticed, while working on this set of docs, that while I knew that
it was based upon Struts, that fact doesn't leak out into "the beehive
way of building applications". But if a firm choses Beehive, learning
that it's based upon struts might definitely be an 'a-ha!', where they
feel more comfortable with it due to availability of online knowledge,
experts and books at the bookstore.
Sure, I agree. I think this could also be a valuable one-sentence or
one-phrase addition. In almost all blurbs about NetUI, the fact that
it's built on Struts leaks out.
So, that's probably way more words than you wanted, without a concrete
answer. :) I just think docs benefit from use-cases as much as software,
and the use-case for extended feature lists and underpinning technology
information is slightly different than that of answering the "why do I care?"
question.
Just want to make clear that I think what you're doing (overview) is
extremely valuable... so much so that if it's not present, there will be
a large set of people who will never even try the technology.
The docs you're speaking of, I see being valuable after a user has decided
"okay, I think I care, beehive looks cool, but is it something we want
to build our application with? What are the risks and rewards of using
beehive?"
-bob
Thanks,
Rich
