struts-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Philip Luppens" <philip.lupp...@gmail.com>
Subject Re: Users guide
Date Mon, 12 Feb 2007 16:07:11 GMT
On 2/12/07, Tom Schneider <schneidh@gmail.com> wrote:
> 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.

I agree; that's why I made that remark about the Developers Guide
being neither a real developer's resource, nor a real reference guide.
Maybe it's indeed better to split this all up:

Installation guide: installing Struts 2
User guide: architecture (high level), what is what, how does it work
(high level), ..
Tutorials: Hello World, first form, mailreader, crud, ..
Developer guide: architecture, extension points, plugin system, ..
Reference guide: full reference
Plugin guide(s): Spring, SWF, JFree, Tables, GWT, ..

I'm quite aware that this is a lot of work. But if we don't do it now
properly, I'm afraid we'll regret it later (or at least our users).

Phil

> Tom
>
> On 2/12/07, Philip Luppens <philip.luppens@gmail.com> wrote:
> > On 2/12/07, Musachy Barroso <mbarroso@wfscorp.com> 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: dev-unsubscribe@struts.apache.org
> > > For additional commands, e-mail: dev-help@struts.apache.org
> > >
> > >
> >
> >
> > --
> > 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: dev-unsubscribe@struts.apache.org
> > For additional commands, e-mail: dev-help@struts.apache.org
> >
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
>


-- 
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: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org


Mime
View raw message