On 2/12/07, Musachy Barroso <[EMAIL PROTECTED]> wrote:
> It's also not clear whether the intention is to create new content or > link to the old. I think the idea is just to organize the info in a way that a user new to struts 2 can understand. From my personal experience, when I started with S2, I couldn't make sense out of the wiki, I had to read WW in Action, and after that, the wiki was just great!
Well, the first point is: what belongs in a user guide ? Is it just an 'easier' Developers Guide ? Does it contain examples ? Or rather tutorials ? Should it contain links to the reference pages ? Isn't the Developers Guide in fact our Reference Guide ? Should we split it up ? To be honest, I find it very hard to imagine what a newbie thinks or expects from a user guide. Does the User Guide take a new user to the point where he or she can create basic Actions, views (JSP, Freemarker, Velocity, ..), and set up a basic configuration (struts.xml) ? In that case, shouldn't a big tutorial be easier ? The Developers Guide is supposed to give insights into the inner workings of Struts 2, about extension points (Interceptors, Plugins, PreResultListeners, ..), but right now, it looks more like the reference guide. So, let's decide what guides we want (installation guide, user guide, developer guide, reference, tutorial, ..), and what the goal/outline for each guide is. I admit: the current guide and outline is not for newbies. Part of Struts success was its excellent Users Guide, something I really want to see in Struts 2 - because it would greatly impact the success of Struts 2 amongst new programmers. But, like we point out below: there are books going to be written (and being written), so we might leave the authors of those books something to tell ;-) All kidding aside: I really like the Hibernate documentation: a simple getting started example, and a user guide. Plus there's the Hibernate in action book that lists best practices and designs. Maybe that's a good example ?
> My suggestion would be to look at the existing content as an > encyclopedia (or wikipedia), augmented by tutorials and FAQs. > Personally, I'd suggest putting the effort into expanding the > bootstrap tutorial, merging it with the CRUD tutorial, making sure all > the FAQs on the list actually end up in the FAQ, and making the rest > of the wiki the best encylopedia that it can be. There are also still > many places where we don't use snippets hard enough, and so the > content is out of date.
Ideally, the content should indeed be put on one place. Otoh, esp. for the user guide, I do not expect it to change that much (or much at all). We aren't suddently going to drop Results, we aren't tossing away actions, ... etc. More advanced things belong in the Developers Guide or Reference Guide. Maybe it's a good idea to take a look at the Architecture Image [1], and decide what should be explained in what part ? eg. We can briefly explain what interceptors are, and what they do, but refer to the Reference Guide (which then contains the snippets) for specific information, and the Developers Guide for writing your own Interceptor.
Good point. We could definitely consider that, because I think it would be good enough, to get the bootstrap edited and beefed up. The other problem would be duplicated documentation which would be hard to maintain. Besides, there's got to be a couple of S2 books on the make. Phil?
Yes; afaik, Ian is working on both a book for the 3th quarter of the year, and a minibook (about 60 pages) is supposed to hit InfoQ nex month.
> But, we all have to scratch our own itches, and if a book-style user > guide is your itch, more power to you :) Well, I don't like writing at all, but I worry about the newbies :) .
Same here, a good user guide was something that was always postponed at WW, and something that can definitely make the difference between a good and a great framework (in terms of success). I don't mind writing at all, but like I pointed out before: I'm afraid I've lost touch with new programmers' problems or wishes when trying WW/Struts 2, so someone who hasn't been involved with WW/Struts 2 would make a good candidate for doing the reviews and/or proposing ideas. Cheers, Phil [1] http://cwiki.apache.org/WW/the-struts-2-request-flow.html
musachy --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
-- iDTV System Engineer "Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live." - John F. Woods --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
