[seam-dev] getting started first draft

[Jordan Ganoff]

I agree, this looks good. However, the link to the seam-example-confbuzz
github project is broken on the ConfBuzz getting started guide (
http://seam.awestruct.org/tutorial/index.html). It should be
https://github.com/seam/seam-example-confbuzz.

Great start!

Best,
Jordan

On Tue, Aug 23, 2011 at 10:12 AM, Pete Muir <pmuir at 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 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
>
>
> _______________________________________________
> seam-dev mailing list
> seam-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/seam-dev
>



-- 
Jordan Ganoff
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/seam-dev/attachments/20110823/e891368d/attachment.html