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]
