struts-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Musachy Barroso <mbarr...@wfscorp.com>
Subject Re: Users guide
Date Mon, 12 Feb 2007 17:55:28 GMT
Could we merge the "users guide" with the bootstrap tutorial? Adding an 
introduction/overview and explaining the concepts along the tutorials?

musachy

Philip Luppens wrote:
> 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
>>
>>
>
>


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org


Mime
View raw message