Re: [seam-dev] getting started first draft

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(a)gmail.com&gt; wrote: > On Fri, Aug 19, 2011 at 04:17, Jason Porter <lightguard.jp(a)gmail.com&gt;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(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/seam-dev > > -- Daniel Hinojosa Programmer, Instructor, and Consultant dhinojosa(a)evolutionnext.com http://www.evolutionnext.com http://www.abqjug.org