I agree, this looks good. However, the link to the seam-example-confbuzz
github project is broken on the ConfBuzz getting started guide (
). It should be
On Tue, Aug 23, 2011 at 10:12 AM, Pete Muir <pmuir(a)redhat.com> wrote:
I took a quick look at this, it's very nicely done, nice job!
Config is a difficult one, a everyone needs it once, and never again....
Dan's suggestion is good I think.
On 19 Aug 2011, at 22:44, Dan Allen wrote:
> On Fri, Aug 19, 2011 at 04:17, Jason Porter <lightguard.jp(a)gmail.com>
> I would greatly appreciate feedback people have for the items in
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
> - 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.
> "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
> I think you can re-purpose the existing content into this new structure
> Let me know if you need more specific feedback.
> 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
> seam-dev mailing list
seam-dev mailing list