You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@struts.apache.org by Musachy Barroso <mu...@gmail.com> on 2007/02/12 03:38:36 UTC
Users guide
Phil and I started to work on a "User Guide" that resembles the one from S1,
to help new users learn S2:
http://cwiki.apache.org/confluence/display/WW/User+Guide
Every time you contribute to this guide, a donation will be made to the New
Users Foundation :)
musachy
--
"Hey you! Would you help me to carry the stone?" Pink Floyd
Re: Users guide
Posted by Ted Husted <hu...@apache.org>.
On 2/12/07, Musachy Barroso <mb...@wfscorp.com> wrote:
> 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!
In the beginning, I had to dissect the MailReader to figure it out,
which lead to the MailReader Tour.
Again, a slonger tutorial that included the CRUD stuff would help
orientate people so that they have a "framework of reference" for the
rest of framework reference :)
What might be helpful would be to break it down into guides that
follow the natural flow of the framework. So, within the Core Guide,
we might have Architecture, Configuration, Validation, Interceptors,
Results, and Actions.
Core Guide
* Architecture
o AJAX
o ObjectFactory
o Dependency Injection
+ Spring
+ Plexus
o Profiling
o Debugging
* Configuration
o Annotations
o Zero Configuration
o Struts Configuration Elements
o Action Mapper & Action Mapping
o ActionMapper
o Wildcard Mappings
o Configuration Provider & Configuration
o Configuration Files
+ web.xml
+ struts.xml
+ struts.properties
+ struts-default.xml
+ velocity.properties
+ struts-default.vm
o Application Servers
* Validation
o Type Conversion
o Localization
* Interceptors
o Interceptor Types
* Actions
o Action Proxy & ActionProxy Factory
o Action Chaining
* Results
o Result Types
o DispatcherListener
o PreResultListener
That's everything we have now as top-level links, except for the
plugin registry and portlet stuff, which should go under plugins.
The key might be to have a decent overview in the Architecture
section. Jason's presentation would be a good starting point for that.
* http://opensource.atlassian.com/confluence/oss/download/attachments/829/webwork.pdf
> 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.
Yes. There *must not* be duplicated content, unless it is the form of
a tutorial or FAQ meant to point to the rest of the documentation.
Even then, we should try to cross-reference bits, so that the guide
entries point to the FAQs and tutorial sections. Then, when we update
a page in the guide, it will be easier to check to see if the tutorial
and FAQs are current.
> Besides, there's got to be a couple of S2 books on the make. Phil?
>
> > 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 :) .
>
> musachy
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Users guide
Posted by Ted Husted <hu...@apache.org>.
Based on this thread, and some others, I've rearranged the pages in
the Core Developers Guide to follow the natural flow of the framework.
* http://struts.apache.org/2.x/docs/guides.html
For now, I've also added markers for some "missing pages" that would
help fill in the gaps. For example, we don't actually have a page
devoted to the Action class, nor do we have pages devoted to writing
other custom classes, like Interceptors or Validators, even though
that's something most of us do at one time or the other.
I also extracted pages dealing with the deep internals into an
Architects Guide. Most folk do not need to know much about the
ObjectFactory or ActionMappers. But for those that do, we should have
an area where we can discuss the gritty details.
Meanwhile, I continue to think that the most helpful "next step" would
be to merge the bootstrap tutorial with one of the WW CRUD tutorials,
but that's not something I can address myself right now.
-Ted.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Users guide
Posted by Paul Benedict <pb...@apache.org>.
Copy what is successful: The Spring Framework Reference Guide. That kind
of thing is awesome and is basically a book in itself:
http://static.springframework.org/spring/docs/2.0.x/reference/index.html
I don't know what format they write it in, but they export identical
texts to both HTML and PDF.
Paul
Tom Schneider 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.
> Tom
>
> On 2/12/07, Philip Luppens <ph...@gmail.com> wrote:
>> On 2/12/07, Musachy Barroso <mb...@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
Re: Users guide
Posted by Musachy Barroso <mb...@wfscorp.com>.
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 <sc...@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 <ph...@gmail.com> wrote:
>> > On 2/12/07, Musachy Barroso <mb...@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
Re: Users guide
Posted by Philip Luppens <ph...@gmail.com>.
On 2/12/07, Tom Schneider <sc...@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 <ph...@gmail.com> wrote:
> > On 2/12/07, Musachy Barroso <mb...@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
Re: Users guide
Posted by Tom Schneider <sc...@gmail.com>.
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 <ph...@gmail.com> wrote:
> On 2/12/07, Musachy Barroso <mb...@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
Re: Users guide
Posted by Philip Luppens <ph...@gmail.com>.
On 2/12/07, Musachy Barroso <mb...@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
Re: Users guide
Posted by Musachy Barroso <mb...@wfscorp.com>.
> 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!
> 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.
>
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?
> 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 :) .
musachy
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Users guide
Posted by Dave Newton <ne...@yahoo.com>.
--- Niall Pemberton <ni...@gmail.com> wrote:
> [...]
I guess there's also a {float...} element; I tried a
little test on the Result annotation page (not much in
it, proof-of-concept).
It might be a good way to get links to additional info
w/o breaking the default "flow" of the page.
Dave
____________________________________________________________________________________
8:00? 8:25? 8:40? Find a flick in no time
with the Yahoo! Search movie showtime shortcut.
http://tools.search.yahoo.com/shortcuts/#news
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Users guide
Posted by Niall Pemberton <ni...@gmail.com>.
On 2/14/07, Dave Newton <ne...@yahoo.com> wrote:
> One thing that would help "clean up" the wiki guides
> is to format it more like a book: sidebars really work
> and are much less disruptive than a browser-width
> highlighted section. I don't know if that's possible
> with Confluence, but it sure could be handy.
Stripes uses confluence and has index/contents on the left:
http://stripes.mc4j.org/confluence/display/stripes/Home
http://raibledesigns.com/rd/entry/confluence_installed_for_appfuse_2
Niall
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Users guide
Posted by Ted Husted <hu...@apache.org>.
Sadly, Hibernate's a bit of sticky wicket, because of the whole LGPL thing.
We could do iBATIS, or Spring JDBC, or JPA, or anything under a
compatible license.
* http://people.apache.org/~cliffs/3party.html
I've been wondering if Hibernate or iBATIS plugins would make any sense.
As to the CRUD sections, we could just start by adding a "Accessing
Data" section after after "Localizing Input", or create a "Part 2:
CRUD", if that seems more appropriate.
-Ted.
On 2/14/07, Philip Luppens <ph...@gmail.com> wrote:
> Ok, sounds fine to me. Then we'll drop the User Guide, and start
> writing on those missing chapters.
>
> Btw, the crud tutorial: should we make a part II where we use a real
> database (in combination with Spring and Hibernate) ? I've updated it
> and verified it to work on S2, but WW-1711 is used in the tutorial, so
> I'm not closing the Jira issue yet.
>
> Cheers,
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Users guide
Posted by Ted Husted <hu...@apache.org>.
Would a layout like Groovy make what we have more accessible?
* http://groovy.codehaus.org/
On 2/14/07, Philip Luppens <ph...@gmail.com> wrote:
> Ok, sounds fine to me. Then we'll drop the User Guide, and start
> writing on those missing chapters.
>
> Btw, the crud tutorial: should we make a part II where we use a real
> database (in combination with Spring and Hibernate) ? I've updated it
> and verified it to work on S2, but WW-1711 is used in the tutorial, so
> I'm not closing the Jira issue yet.
>
> Cheers,
>
> Phil
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Users guide
Posted by Philip Luppens <ph...@gmail.com>.
Ok, sounds fine to me. Then we'll drop the User Guide, and start
writing on those missing chapters.
Btw, the crud tutorial: should we make a part II where we use a real
database (in combination with Spring and Hibernate) ? I've updated it
and verified it to work on S2, but WW-1711 is used in the tutorial, so
I'm not closing the Jira issue yet.
Cheers,
Phil
On 2/14/07, Ted Husted <hu...@apache.org> wrote:
> In Struts in Action, as with many text books, we included "Developer
> information" at the foot of a section or chapter as appropriate. So
> first, we covered the "user" material and then we covered the
> "developer" material, without creating two content streams. I don't
> see that mixing the two is a bad thing, or that separating the two is
> a good thing. Users do need to know that the framework is extensible,
> even if they don't want to extend it today.
>
> I would agree it would be helpful to add more "Developer information"
> to the project documentation, by adding pages for "Writing
> Interceptors" and "Writing Actions".
>
> * http://struts.apache.org/2.x/docs/guides.html
>
> People who don't want to write such things now, can just skip past
> those pages, until the occasion arises.
>
> Once place where I'd say we could use a separate guide is where we get
> into internal components, like the ObjectFactory and ActionMappers,
> which could be push into a separate "Architects Guide".
>
> * http://struts.apache.org/2.x/docs/architects-guide.html
>
> I would also agree that the bootstrap tutorial should be extended to
> include a CRUD tutorial. After a longer tutorial, I believe any
> reasonable person could read and understand the rest of the
> documentation.
>
> -Ted.
>
>
> On 2/14/07, Philip Luppens <ph...@gmail.com> wrote:
> > I understand we don't want duplicated docs, but at the moment, we have
> > to realize our Developers Guide is a mix of a Users Guide, Developers
> > Guide and Reference Guide.
> > If we take the following 'definitions' into account:
> >
> > - Developers: in-depth architecture, creating and extending
> > Interceptors, Results, Validators, Themes, Templates, Plugins, ..
> >
> > - Users: explain the high level architecture, create Actions, create
> > Views, configuration of the webapp (struts.xml, using annotations,
> > mapping, ..), ..
> >
> > - Reference: contains the explanation and docs for each Validator,
> > Interceptor, Result, Annotation, .. by using the snippet macro.
> >
> > I believe we can rearrange the docs fairly easily based on the list
> > above (I understand it would mean a lot of work - but I'm ok with that
> > and willing to step up for it). The amount of duplicated docs should
> > be reduced to a minimum.
> >
> > Otoh, we could keep the current Developers Guide, and just provide an
> > 'easy' outline or view for users that links to the current Developers
> > Guide.
> >
> > Thoughts ?
> >
> > Phil
>
> ---------------------------------------------------------------------
> 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
Re: Users guide
Posted by Dave Newton <ne...@yahoo.com>.
--- Ted Husted <hu...@apache.org> wrote:
> So first, we covered the "user" material and then we
> covered the "developer" material, without creating
> two content streams.
FWIW, I think two completely separate content streams
is definitely a Bad Thing. I'd rather see a tutorial
with sidebars containing more detailed information,
links to more detailed information, or both.
One thing that would help "clean up" the wiki guides
is to format it more like a book: sidebars really work
and are much less disruptive than a browser-width
highlighted section. I don't know if that's possible
with Confluence, but it sure could be handy.
Another nice thing would be to have links to both wiki
Guide sections and even JavaDocs throughout the pages
(particularly the tutorial-level pages) for all the
elements discussed on the page: configurations,
annotations, classes, related tasks, etc.
> Users do need to know that the framework is
> extensible, even if they don't want to extend it
> today.
Figuring out where and *why* to extend things is
critical... In S2 one great place to add functionality
is in the interceptors, even if it's just configuring
an existing one. The note on the wiki that says you
probably won't need to do that is somewhat misleading,
IMO.
For example, yesterday I wanted a trivial way to add
behavior to arbitrary methods on a per-Action basis
without changing any Action code. So I wrote an
interceptor that took as parameters "methodName:
monitor1,monitor2" etc.
That was great and worked until I discovered such an
interceptor already existed, it just wasn't listed on
the interceptor Guide page (MethodFilterInterceptor).
Much lighter-weight than Spring AOP, and perfect for
what I needed. For all I know there's a still-better
way to implement it (wouldn't surprise me).
Highlighting trivial extensibility goes a *long* way
towards users a) not asking dorky questions (like me
:) and b) really understanding the simplicity of the
framework and utilizing its extensibility and
cleanliness--my Action code is like 15 lines long but
I can bolt on non-invasive functionality by writing a
simple class and adding it to the list of "extra crap
to do" items.
My time is pretty limited these days, but I'm happy to
help clean up, expand, notate, whatever the
documentation (best way to learn!) as much as I can
(and I even write real good sometimes :D and if I am
pointed at something specific will take the time to do
it up all purty-like.
Dave
____________________________________________________________________________________
Finding fabulous fares is fun.
Let Yahoo! FareChase search your favorite travel sites to find flight and hotel bargains.
http://farechase.yahoo.com/promo-generic-14795097
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Users guide
Posted by Ted Husted <hu...@apache.org>.
In Struts in Action, as with many text books, we included "Developer
information" at the foot of a section or chapter as appropriate. So
first, we covered the "user" material and then we covered the
"developer" material, without creating two content streams. I don't
see that mixing the two is a bad thing, or that separating the two is
a good thing. Users do need to know that the framework is extensible,
even if they don't want to extend it today.
I would agree it would be helpful to add more "Developer information"
to the project documentation, by adding pages for "Writing
Interceptors" and "Writing Actions".
* http://struts.apache.org/2.x/docs/guides.html
People who don't want to write such things now, can just skip past
those pages, until the occasion arises.
Once place where I'd say we could use a separate guide is where we get
into internal components, like the ObjectFactory and ActionMappers,
which could be push into a separate "Architects Guide".
* http://struts.apache.org/2.x/docs/architects-guide.html
I would also agree that the bootstrap tutorial should be extended to
include a CRUD tutorial. After a longer tutorial, I believe any
reasonable person could read and understand the rest of the
documentation.
-Ted.
On 2/14/07, Philip Luppens <ph...@gmail.com> wrote:
> I understand we don't want duplicated docs, but at the moment, we have
> to realize our Developers Guide is a mix of a Users Guide, Developers
> Guide and Reference Guide.
> If we take the following 'definitions' into account:
>
> - Developers: in-depth architecture, creating and extending
> Interceptors, Results, Validators, Themes, Templates, Plugins, ..
>
> - Users: explain the high level architecture, create Actions, create
> Views, configuration of the webapp (struts.xml, using annotations,
> mapping, ..), ..
>
> - Reference: contains the explanation and docs for each Validator,
> Interceptor, Result, Annotation, .. by using the snippet macro.
>
> I believe we can rearrange the docs fairly easily based on the list
> above (I understand it would mean a lot of work - but I'm ok with that
> and willing to step up for it). The amount of duplicated docs should
> be reduced to a minimum.
>
> Otoh, we could keep the current Developers Guide, and just provide an
> 'easy' outline or view for users that links to the current Developers
> Guide.
>
> Thoughts ?
>
> Phil
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Users guide
Posted by Philip Luppens <ph...@gmail.com>.
I understand we don't want duplicated docs, but at the moment, we have
to realize our Developers Guide is a mix of a Users Guide, Developers
Guide and Reference Guide.
If we take the following 'definitions' into account:
- Developers: in-depth architecture, creating and extending
Interceptors, Results, Validators, Themes, Templates, Plugins, ..
- Users: explain the high level architecture, create Actions, create
Views, configuration of the webapp (struts.xml, using annotations,
mapping, ..), ..
- Reference: contains the explanation and docs for each Validator,
Interceptor, Result, Annotation, .. by using the snippet macro.
I believe we can rearrange the docs fairly easily based on the list
above (I understand it would mean a lot of work - but I'm ok with that
and willing to step up for it). The amount of duplicated docs should
be reduced to a minimum.
Otoh, we could keep the current Developers Guide, and just provide an
'easy' outline or view for users that links to the current Developers
Guide.
Thoughts ?
Phil
On 2/14/07, Ted Husted <hu...@apache.org> wrote:
> I don't have the time to work on a significant refactoring this year.
> The most I can do is help keep what we have patched and up-to-date.
>
> As a PMC member, I would be opposed to any project-sanctioned effort
> that is going to create a set of redundant documents that would be
> made part of a release. We have to be very sensitive to the limited
> time our volunteers have available. We're lucky if we have time to
> update the project documentation in one place, let alone three or four
> different places.
>
> But, if someone wants to start something on the S2 wiki site (S2WIKI),
> or in the sandbox, to see if there's traction among other volunteers,
> the rules of revolution would apply.
>
> As to other parts of this thread, I'm not convinced that an XML format
> would be the best thing for Struts 2. There's a lot to be said for
> people being able to make changes in real time. With Confluence,
> anyone with a CLA on file can pitch in and help. (And thanks very much
> to those that already do!) Without a wiki, we're back to patches that
> have to applied by committers. Of course, there is a DocBook Wiki, but
> first we'd have to address the infrastructure issues.
>
> Since the Struts 1 project documentation is already in XML, that's "a
> horse of a different color".
>
> -Ted.
>
>
> On 2/14/07, Philip Luppens <ph...@gmail.com> wrote:
> > Ok, any chance for a summary with roles on who's going to do what, and
> > in what timeframe ?
> >
> > Although limited in spare time (aren't we all), I'm definitely willing
> > to work on this (and I assume Musachy as well), but I would appreciate
> > directions or a concrete plan.
> >
> > Shoot.
> >
> > Phil
>
> ---------------------------------------------------------------------
> 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
Re: Users guide
Posted by Ted Husted <hu...@apache.org>.
I don't have the time to work on a significant refactoring this year.
The most I can do is help keep what we have patched and up-to-date.
As a PMC member, I would be opposed to any project-sanctioned effort
that is going to create a set of redundant documents that would be
made part of a release. We have to be very sensitive to the limited
time our volunteers have available. We're lucky if we have time to
update the project documentation in one place, let alone three or four
different places.
But, if someone wants to start something on the S2 wiki site (S2WIKI),
or in the sandbox, to see if there's traction among other volunteers,
the rules of revolution would apply.
As to other parts of this thread, I'm not convinced that an XML format
would be the best thing for Struts 2. There's a lot to be said for
people being able to make changes in real time. With Confluence,
anyone with a CLA on file can pitch in and help. (And thanks very much
to those that already do!) Without a wiki, we're back to patches that
have to applied by committers. Of course, there is a DocBook Wiki, but
first we'd have to address the infrastructure issues.
Since the Struts 1 project documentation is already in XML, that's "a
horse of a different color".
-Ted.
On 2/14/07, Philip Luppens <ph...@gmail.com> wrote:
> Ok, any chance for a summary with roles on who's going to do what, and
> in what timeframe ?
>
> Although limited in spare time (aren't we all), I'm definitely willing
> to work on this (and I assume Musachy as well), but I would appreciate
> directions or a concrete plan.
>
> Shoot.
>
> Phil
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Users guide
Posted by Philip Luppens <ph...@gmail.com>.
Ok, any chance for a summary with roles on who's going to do what, and
in what timeframe ?
Although limited in spare time (aren't we all), I'm definitely willing
to work on this (and I assume Musachy as well), but I would appreciate
directions or a concrete plan.
Shoot.
Phil
On 2/14/07, Ted Husted <hu...@apache.org> wrote:
> On 2/13/07, Paul Benedict <pb...@apache.org> wrote:
> > Yup. Spring uses Docbook. That's what I am going to try: single html
> > page (everything), multiple html pages, and PDF.
>
> For DocBook under Windows, I've been having good luck with
>
> * TextPad
> * xlstproc
> * Apache FOP
>
> The trick is to use xmllint frequently to catch any formatting oversights.
>
> TextPad has plugins for DocBook syntax. The TextPad cliplibraries work
> surprisingly well for XML formatting, and give you more control over
> the source. An issue with the IDEs is that they tend to format
> everything as one long line, making repository change logs useless.
> (And repository change logs is one very good reason to use DocBook!)
>
> Besides supporting a variety of output formats, another key benefit
> for geeks is that the code examples can be stored as external files,
> so you can continue to edit and test them with programming tools, or
> maybe even suck them in from the distribution, snippet style.
>
> DocBook ReadMeFirst
>
> * TextPad DocBook - http://www.scottnesbitt.net/techdocs/docbook_textpad.html
> * CodeProject DocBook - http://www.codeproject.com/winhelp/docbook_howto.asp
> * DocBook XSL - http://www.sagehill.net/book-description.html
> * DocBook Guide -
> http://www.oasis-open.org/docbook/documentation/reference/html/docbook.html
>
> DocBook Downloads
>
> * DocBook XLS - http://sourceforge.net/projects/docbook/
> * DocBook DTD - http://www.oasis-open.org/docbook/xml/
> * DTD Character Entities -
> http://www.oasis-open.org/docbook/xmlcharent/index.shtml
> * TextPad - http://www.textpad.com/
> * SDocBook clip library - http://www.textpad.com/add-ons/cliplibs.html
> * DocBook syntax - http://www.textpad.com/add-ons/syna2g.html
> * xsltproc - http://www.zlatkovic.com/pub/libxml/ - libxml, libxslt,
> zlib, and iconv
> ** libxml2-2.6.27.win32 (includes xmllint)
> ** libxslt-1.1.17.win32
> ** zlib-1.2.3.win32
> ** iconv-1.9.2.win32.zip
> * Apache FOP - http://www.apache.org/dyn/closer.cgi/xmlgraphics/fop
> ** Java Advanced Imaging (JAI)
> https://jai.dev.java.net/binary-builds.html#Release_builds
> ** Objects for Formatting Objects http://sourceforge.net/projects/offo/
>
> If there's ever a week when I'm not rolling a Struts 2 release, I
> might blog about DocBook under Windows. :)
>
> -- HTH, Ted.
> * http://www.husted.com/struts/
>
> ... or, maybe when wrestling season is over and I get my Saturdays
> back. My son just won the Sectional wrestling championship hereabouts,
> which puts him one step away from the NYS tournament.
>
> ---------------------------------------------------------------------
> 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
Re: Users guide
Posted by Ted Husted <hu...@apache.org>.
On 2/13/07, Paul Benedict <pb...@apache.org> wrote:
> Yup. Spring uses Docbook. That's what I am going to try: single html
> page (everything), multiple html pages, and PDF.
For DocBook under Windows, I've been having good luck with
* TextPad
* xlstproc
* Apache FOP
The trick is to use xmllint frequently to catch any formatting oversights.
TextPad has plugins for DocBook syntax. The TextPad cliplibraries work
surprisingly well for XML formatting, and give you more control over
the source. An issue with the IDEs is that they tend to format
everything as one long line, making repository change logs useless.
(And repository change logs is one very good reason to use DocBook!)
Besides supporting a variety of output formats, another key benefit
for geeks is that the code examples can be stored as external files,
so you can continue to edit and test them with programming tools, or
maybe even suck them in from the distribution, snippet style.
DocBook ReadMeFirst
* TextPad DocBook - http://www.scottnesbitt.net/techdocs/docbook_textpad.html
* CodeProject DocBook - http://www.codeproject.com/winhelp/docbook_howto.asp
* DocBook XSL - http://www.sagehill.net/book-description.html
* DocBook Guide -
http://www.oasis-open.org/docbook/documentation/reference/html/docbook.html
DocBook Downloads
* DocBook XLS - http://sourceforge.net/projects/docbook/
* DocBook DTD - http://www.oasis-open.org/docbook/xml/
* DTD Character Entities -
http://www.oasis-open.org/docbook/xmlcharent/index.shtml
* TextPad - http://www.textpad.com/
* SDocBook clip library - http://www.textpad.com/add-ons/cliplibs.html
* DocBook syntax - http://www.textpad.com/add-ons/syna2g.html
* xsltproc - http://www.zlatkovic.com/pub/libxml/ - libxml, libxslt,
zlib, and iconv
** libxml2-2.6.27.win32 (includes xmllint)
** libxslt-1.1.17.win32
** zlib-1.2.3.win32
** iconv-1.9.2.win32.zip
* Apache FOP - http://www.apache.org/dyn/closer.cgi/xmlgraphics/fop
** Java Advanced Imaging (JAI)
https://jai.dev.java.net/binary-builds.html#Release_builds
** Objects for Formatting Objects http://sourceforge.net/projects/offo/
If there's ever a week when I'm not rolling a Struts 2 release, I
might blog about DocBook under Windows. :)
-- HTH, Ted.
* http://www.husted.com/struts/
... or, maybe when wrestling season is over and I get my Saturdays
back. My son just won the Sectional wrestling championship hereabouts,
which puts him one step away from the NYS tournament.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Users guide
Posted by Paul Benedict <pb...@apache.org>.
Yup. Spring uses Docbook. That's what I am going to try: single html
page (everything), multiple html pages, and PDF. Spring distro has this:
====
We're using the DocBook XSL distribution for HTML and PDF
generation. The best results can be achieved with the
Saxon XSLT processor (don't use Xalan!) and the Apache
FOP library.
The documentation is generated by Spring's build.xml file
for Ant. Targets included are:
* doc.pdf - generates the PDF documentation
* doc.html - generates the HTML documentation
* doc.htmlsingle - generates single page HTML documentation
* doc.clean - clean any output directories for docs
To generate documentation, you need to include a lot
of libraries, which haven't been added to CVS because
they're simply too big. The libraries can be found at:
http://static.springframework.org/spring/files/docbook-reference-libs.zip.
Download them, create a lib directory in the
docs/reference directory and unzip the zip there.
Then, the targets should work.
===
Paul
Wendy Smoak wrote:
> On 2/13/07, Paul Benedict <pb...@apache.org> wrote:
>> I agree with Ted's comments on the S1 layout. I am going to try some
>> experimenting with the Struts 1 User Guide for the 1.4 release and what
>> else we can do with it. I'll just do it for fun and see if I can make
>> HTML and PDF documents from one source. Stay tuned.
>
> Did you find out what Spring uses?
>
> Docbook will certainly do it. There are two Maven plugins that I know of.
>
> There was a very nice pdf plugin for Maven 1, but so far nothing even
> close for m2. There's some work done in "Doxia Book" which uses
> iText, but I wasn't impressed with the output.
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Users guide
Posted by Wendy Smoak <ws...@gmail.com>.
On 2/13/07, Paul Benedict <pb...@apache.org> wrote:
> I agree with Ted's comments on the S1 layout. I am going to try some
> experimenting with the Struts 1 User Guide for the 1.4 release and what
> else we can do with it. I'll just do it for fun and see if I can make
> HTML and PDF documents from one source. Stay tuned.
Did you find out what Spring uses?
Docbook will certainly do it. There are two Maven plugins that I know of.
There was a very nice pdf plugin for Maven 1, but so far nothing even
close for m2. There's some work done in "Doxia Book" which uses
iText, but I wasn't impressed with the output.
--
Wendy
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Users guide
Posted by Paul Benedict <pb...@apache.org>.
I agree with Ted's comments on the S1 layout. I am going to try some
experimenting with the Struts 1 User Guide for the 1.4 release and what
else we can do with it. I'll just do it for fun and see if I can make
HTML and PDF documents from one source. Stay tuned.
Ted Husted wrote:
> After six years of maintaining the Struts 1 User Guide, for what its
> worth, here's some personal feedback.
>
> * Separating the content into model, view, and controller sections is
> often problematic since most workflows cross that boundary. It's hard
> to discuss a routine task beginning to end.
>
> * It's often hard to decide where to place a new feature. Toward, the
> end, things just started to get tacked on to the end. We see that
> happending again with sections about "plugins" and "portlets".
>
> Another key problem, that snippets would help cure, is keeping
> embedded examples in sync with changes to the code base.
>
> It's also not clear whether the intention is to create new content or
> link to the old. I can tell you that significant refactorings in
> Confluence are a lot of work. (And that's coming from a guy who
> obviously doesn't mind hard work.) I really enjoy the quick, roundtrip
> editing a wiki like Confluence provides, but large scale structural
> changes are very, very painful.
>
> 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.
>
> But, we all have to scratch our own itches, and if a book-style user
> guide is your itch, more power to you :)
>
> Just, please, please, please, keep in mind that we have to maintain
> the documentation over the very long term, and we need to keep the
> content normalized and update friendly.
>
> -Ted.
>
>
> On 2/11/07, Musachy Barroso <mu...@gmail.com> wrote:
>> Phil and I started to work on a "User Guide" that resembles the one
>> from S1,
>> to help new users learn S2:
>>
>> http://cwiki.apache.org/confluence/display/WW/User+Guide
>>
>> Every time you contribute to this guide, a donation will be made to
>> the New
>> Users Foundation :)
>>
>> musachy
>>
>> --
>> "Hey you! Would you help me to carry the stone?" Pink Floyd
>
> ---------------------------------------------------------------------
> 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
Re: Users guide
Posted by Ted Husted <hu...@apache.org>.
After six years of maintaining the Struts 1 User Guide, for what its
worth, here's some personal feedback.
* Separating the content into model, view, and controller sections is
often problematic since most workflows cross that boundary. It's hard
to discuss a routine task beginning to end.
* It's often hard to decide where to place a new feature. Toward, the
end, things just started to get tacked on to the end. We see that
happending again with sections about "plugins" and "portlets".
Another key problem, that snippets would help cure, is keeping
embedded examples in sync with changes to the code base.
It's also not clear whether the intention is to create new content or
link to the old. I can tell you that significant refactorings in
Confluence are a lot of work. (And that's coming from a guy who
obviously doesn't mind hard work.) I really enjoy the quick, roundtrip
editing a wiki like Confluence provides, but large scale structural
changes are very, very painful.
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.
But, we all have to scratch our own itches, and if a book-style user
guide is your itch, more power to you :)
Just, please, please, please, keep in mind that we have to maintain
the documentation over the very long term, and we need to keep the
content normalized and update friendly.
-Ted.
On 2/11/07, Musachy Barroso <mu...@gmail.com> wrote:
> Phil and I started to work on a "User Guide" that resembles the one from S1,
> to help new users learn S2:
>
> http://cwiki.apache.org/confluence/display/WW/User+Guide
>
> Every time you contribute to this guide, a donation will be made to the New
> Users Foundation :)
>
> musachy
>
> --
> "Hey you! Would you help me to carry the stone?" Pink Floyd
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org