[seam-dev] getting started first draft

Daniel Hinojosa dhinojosa at evolutionnext.com
Sat Aug 20 02:29:44 EDT 2011


Seam XXX? I want that module!

I agree on the "forewarn the developer of potential missteps to prevent them
from tripping up early on and getting discouraged".

I do not full agree on "tutorial be more development-oriented rather than
configuration-oriented". Some developers are on a time-constraint and want a
get up and go, and read the development oriented stuff later, or not at
all.  It's a tough balancing act, but sometimes what your developer wants is
based on the time he or she has on their hands.

The only one that I thought was too much for the tutorial was the configXML
since they are slapped with a JPAIdentityStore and other heaviness.  That is
too brutal for a tutorial, or maybe for a tutorial at that particular time
in the tutorial.

Finally I agree fully on a tutorial that is a very tiny app from beginning
to end and in small snippets.  I'd like to see an entity to some "action
beans" and basic CRUD, setting up a Data Source, putting in login
information and security, Seam Catch (which is a pretty good tutorial now, I
wonder why?), Some faces pages, URL rewriting rules, and some XML Config to
prove a point or two.

If it were up to me though, I'd make it fun and make the tutorial a dating
website (just don't call it Seam in Love).



On Fri, Aug 19, 2011 at 3:44 PM, Dan Allen <dan.j.allen at gmail.com> wrote:

> On Fri, Aug 19, 2011 at 04:17, Jason Porter <lightguard.jp at gmail.com>wrote:
>
>> I would greatly appreciate feedback people have for the items in
>> https://github.com/LightGuard/seam_site_awestruct/tree/develop/tutorial.
>> They will be the base for our getting started guide for Seam 3. The pages
>> are backed by an example that can be checked out and built (possibly broken
>> right now, I haven't tried to build / run it for a while).
>>
>>
> Jason, there's a lot of great content in this tutorial so far. I like that
> you cite the motivation for each snippet rather than just saying "paste this
> code". For instance, you do a nice job explaining the purpose of the BOM and
> the need for the Java EE APIs as a provided scope dep. I also like that you
> forewarn the developer of potential missteps to prevent them from tripping
> up early on and getting discouraged.
>
> I would like to see the tutorial be more development-oriented rather than
> configuration-oriented. At first glance of the index, we see that the
> tutorial is structured based on the activation of Seam modules (i.e.,
> configuration). Each section begins with dependency configuration, followed
> by configuration for activating features of Java EE or a Seam module. As a
> reader, I'm looking at this saying "wow, all I'm doing is configuring
> stuff"...and that leaves it being very dry. I don't think this is the right
> way to structure it.
>
> (To cite a very specific example, showing the configuration for the
> transaction interceptor in beans.xml is way too premature. That should be
> added once we visit persistence the first time).
>
> So we are still stuck in the "I can tell you everything you'll need to
> setup so that you can code" mentality. Rather, what we want is, "I want to
> write code, stop me when I need to configure something so I can continue
> writing code." and "How am I doing?" We need to feed the reader those
> rewards and assurances.
>
> What I like about the play framework tutorial is that it focuses on adding
> some code, configuring it to run, then seeing the result. To get there with
> this tutorial, here is the general idea of the structure I would propose:
>
> - Starting the project
> (create an alternative version of the first chapter for starting the
> project using Seam Forge)
> - Creating your first pages with pretty URLs
> - Querying the database and displaying the results
> - Authenticating a user
> - Handling errors gracefully
> - Writing integration tests
> - ...
>
> Then you just cover the configuration as it comes along. Take it in stride.
> If a developer wants to see just the instructions for how to activate a Seam
> module, that's what the reference guide is for. Here we need to be in a
> flow. You should try to show code first, then show the configuration to
> activate it (unless you need the API deps, then maybe switch it) and
> finally, tell them how to run the application at that stage.
>
> For instance, I want to see what's in conferences.xhtml. Maybe at first,
> it's just a shell since we haven't queried the database. So we just have
> placeholders where the data will be. But at least the user can run it and
> see that the pretty URLs are working.
>
> If you want, at the very beginning of each section you can mention which
> modules will get used, and which ones will be activated for the first time.
> Something like:
>
> "In this section, we'll setup Seam Faces and use it to map URLs to JSF
> views. We'll also use more features of Seam XXX that you configured in the
> last section."
>
> I think you can re-purpose the existing content into this new structure
> rather easily.
>
> Let me know if you need more specific feedback.
>
> -Dan
>
> p.s. I also think that this structure will make the tutorial a lot more fun
> to write.
>
> --
> Dan Allen
> Principal Software Engineer, Red Hat | Author of Seam in Action
> Registered Linux User #231597
>
> http://www.google.com/profiles/dan.j.allen#about
> http://mojavelinux.com
> http://mojavelinux.com/seaminaction
>
>
> _______________________________________________
> seam-dev mailing list
> seam-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/seam-dev
>
>


-- 
Daniel Hinojosa
Programmer, Instructor, and Consultant
dhinojosa at evolutionnext.com
http://www.evolutionnext.com
http://www.abqjug.org
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/seam-dev/attachments/20110820/10b3f8bb/attachment.html 


More information about the seam-dev mailing list