Just to add my 2 cents... I agree with Ted that the wiki is a bad place to do long cohesive documents. Would a PDF format be a better choice?
With webwork, what most users had was Jason's/Pat's 'Webwork in Action' in combination with the online documentation. This was a really good combination IMO. I'd love to see something similar for Struts2, but without having to buy a book. (i.e. as part of the core documentation, maybe not quite as extensive as the book was, only the first 5-6 chapters were really relevant in getting started) The other thing I'd like to see is some sort of Developer's/Plugin Developer's guide. This is the one area where webwork really didn't have anything. (and I mean nothing) I had to dig through the code to figure out most of this stuff. (Not a terrible thing, but something more would have been helpful) This is something that I'll be working on as time permits. Tom On 2/12/07, Philip Luppens <[EMAIL PROTECTED]> wrote:
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]
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
