Definitely a +1 for Dan's suggestions Sent from my iPhone
On Aug 19, 2011, at 17:52, Jason Porter <[email protected]> wrote: > Good feedback, thanks Dan. I can work on improving along those lines. > > Anyone else have ideas or a +1 for what Dan suggests? > > Sent from my iPhone > > On Aug 19, 2011, at 15:44, Dan Allen <[email protected]> wrote: > >> On Fri, Aug 19, 2011 at 04:17, Jason Porter <[email protected]> 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 > [email protected] > https://lists.jboss.org/mailman/listinfo/seam-dev
_______________________________________________ seam-dev mailing list [email protected] https://lists.jboss.org/mailman/listinfo/seam-dev
