JPF documentation

[bo...@codehaus.org]

Steveh has been taking care of tutorials, so I dumped effort into
general documentation.  I've got a 4-page docset now for JPFs, which
attempt to gently guide a new user from the top-level concepts all
the way down to building and deploying their webapp.

I still have a few more pages I'd like to add [JPF Patterns, demo
of the power of using annotations when you want to re-org a flow,
etc], but here's a preview:

  http://www.codehaus.org/~bob/beehive/pageflow/pageflow_overview.html

>From there, you can follow the links to the next 3 pages of the set,
or if you want to direct-dial:

  http://www.codehaus.org/~bob/beehive/pageflow/pageflow_controllers.html
  http://www.codehaus.org/~bob/beehive/pageflow/pageflow_jsp.html
  http://www.codehaus.org/~bob/beehive/pageflow/pageflow_building.html

I'd love to have someone double-check the dependency information in the
pageflow_building.html page.

Going to rework the diagrams to be a little less big, also.

Comments muchly welcomed.

Another half-day on this, then I'll do similar treatment for Controls,
distilling information from other existing documentation.

Then, a top-level 10,000ft view of how JPF/Controls and such all fit
together, perhaps.  Something suitable for the front-page of the site.

	-bob

Re: JPF documentation

[Richard Feit <ri...@bea.com>]

Thanks!  :)   Here's hoping we can get the word out effectively...

bob@codehaus.org wrote:

>>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.
>>    
>>
>
>Heh, this actually demonstrates my own lack of knowledge about some
>of the features.  This would be great to weave in to, as you said,
>whet their appetite.  Likewise, I think a page, possibly after
>the 'how do I build an app' page, to dive into these more advanced
>topics would be fantastic.  I just need to learn about them myself.
>Something along the lines of "so, you think what you saw is cool,
>just wait until you take a look at *this*, and really get your
>socks blown off..."
>
>  
>
>>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.
>>    
>>
>
>Thanks muchly.  I'm coming at beehive with virgin eyes, hadn't
>touched it until I met with Eddie/Kyle/Ken a few weeks ago.  So
>there's definite dark corners in my knowledge of what it can do.
>But writing the docs basically for a new user like myself has shown
>me how impressive Beehive truly is.  I was wow'd also when dan
>explained some of the nitty-gritty of Control authoring to me, and
>I hope to do a suitable treatment on docs about controls also.
>
>Was telling Garrett just today that while I probably wouldn't write
>a native Struts app, I look forward to really using Beehive in a
>real application in the near future.  You guys have done a stellar
>job with it all.  Now, just to convince the world of that fact. :)
>
>	-bob
>
>  
>

Re: JPF documentation

[bo...@codehaus.org]

> 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.

Heh, this actually demonstrates my own lack of knowledge about some
of the features.  This would be great to weave in to, as you said,
whet their appetite.  Likewise, I think a page, possibly after
the 'how do I build an app' page, to dive into these more advanced
topics would be fantastic.  I just need to learn about them myself.
Something along the lines of "so, you think what you saw is cool,
just wait until you take a look at *this*, and really get your
socks blown off..."

> 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.

Thanks muchly.  I'm coming at beehive with virgin eyes, hadn't
touched it until I met with Eddie/Kyle/Ken a few weeks ago.  So
there's definite dark corners in my knowledge of what it can do.
But writing the docs basically for a new user like myself has shown
me how impressive Beehive truly is.  I was wow'd also when dan
explained some of the nitty-gritty of Control authoring to me, and
I hope to do a suitable treatment on docs about controls also.

Was telling Garrett just today that while I probably wouldn't write
a native Struts app, I look forward to really using Beehive in a
real application in the near future.  You guys have done a stellar
job with it all.  Now, just to convince the world of that fact. :)

	-bob

Re: JPF documentation

[Richard Feit <ri...@bea.com>]

Thanks for the response -- comments inline.

bob@codehaus.org 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 (bob@codehaus.org), 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

Re: JPF documentation

[bo...@codehaus.org]

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 (bob@codehaus.org), 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.

> 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.

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.  

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.

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.

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

Re: JPF documentation

[Richard Feit <ri...@bea.com>]

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?  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.

Rich

bob@codehaus.org wrote:

>Steveh has been taking care of tutorials, so I dumped effort into
>general documentation.  I've got a 4-page docset now for JPFs, which
>attempt to gently guide a new user from the top-level concepts all
>the way down to building and deploying their webapp.
>
>I still have a few more pages I'd like to add [JPF Patterns, demo
>of the power of using annotations when you want to re-org a flow,
>etc], but here's a preview:
>
>  http://www.codehaus.org/~bob/beehive/pageflow/pageflow_overview.html
>
>>>From there, you can follow the links to the next 3 pages of the set,
>or if you want to direct-dial:
>
>  http://www.codehaus.org/~bob/beehive/pageflow/pageflow_controllers.html
>  http://www.codehaus.org/~bob/beehive/pageflow/pageflow_jsp.html
>  http://www.codehaus.org/~bob/beehive/pageflow/pageflow_building.html
>
>I'd love to have someone double-check the dependency information in the
>pageflow_building.html page.
>
>Going to rework the diagrams to be a little less big, also.
>
>Comments muchly welcomed.
>
>Another half-day on this, then I'll do similar treatment for Controls,
>distilling information from other existing documentation.
>
>Then, a top-level 10,000ft view of how JPF/Controls and such all fit
>together, perhaps.  Something suitable for the front-page of the site.
>
>	-bob
>
>  
>