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]
