struts-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Ted Husted" <hus...@apache.org>
Subject Re: [Struts Wiki] Update of "StrutsDocComments" by MichaelJouravlev
Date Sat, 22 Jul 2006 17:34:54 GMT
On 7/22/06, Michael Jouravlev <jmikus@gmail.com> wrote:
> I would really like to rewrite the whole User's Guide, but this is too
> much of a job, and someone would have to proofread it after this
> anyway ;) So I will try to incorporate wiki information into the
> Manual, along with the pictures of course.

I really like the way the Struts 2 documentation is shaping up.

* http://struts.apache.org/2.x/index.html

There isn't a user guide per se. There are Tutorials, FAQs, and a
reference section (Guides).

I'm going to shore-up the Soup-to-Nuts tutorial this weekend. It'll
step through creating an initial workflow. The S2N will be a good
complement to the MailReader tour, which edges into the more
complicated and realistic workflows.

In the long term, I'd like to add tours for the other example
applications, and I'd like migrate the Showcase to a cookbook format,
so that people can both exercise and review the code samples.

It's been my experience that the user guide format is very difficult
to maintain as an open source resource. It's a nice to have, but I
think the most effective resources for us to maintain are jumpstart
tutorials,  FAQ and mini-HOWTOS,  reference resources, and, most
importantly, best-practice example applications.


> Struts does not really have a style guide.

Struts 2 has a start on a documentation style guide here:

*

but it's focussed on Confluence.

There are some practices. I
> like "web resource" instead of "action class"

Hmmm, a web resource is usually taken to mean anything that can be
accessed by a URI and returns a response. While an Action class can
return the response, it is not a web resource per se, since it doesn'
thave it's own URI. The action mapping could be construed as a web
resource, but this term usually means server pages, servlets, or
perhaps a SOAP service.

For a generic reference to Action class, I'd strongly suggest the term
"action handler". In Struts 1, this can include scripts instead of
Java classes, as well as Commands. In Struts 2, the Actoin class
doesn't even need to implement Action, any POJO will do.

> or "view" instead of  "JSP page".

In this vien, I try to refer to "server pages" rather than JSP, since
Velocity and Freemarker templates can be construed as "server pages",
along with, say, PHP templates.

Of course, both S1 and S2 support alternatives to server pages, such
as XLST and PDF.

> On the other hand I would like to suggest users a limited
> set of best (or at least common) practices, so they would not wander
> between countless possibilities. Look at ASP.NET, there is very
> limited choice of how things are done, but users are in fact happy.

If you by users, you mean developers, I'm not sure that's the case.

Given the choice, many ASP.NET developers will use non-Microsoft
solutions. There's a lot of intertest in database access technologies,
like iBATIS.NET and Hibernate.NET, as well as logging solutions, like
Apache Logging. IMHO, people don't use ASP.NET so much because they
like it, as much as because they've been told to use it, and there
aren't many alternatives. (Just wait until people are able to choose
Struts 2 for C#, PHP, or Ruby!)

Meanwhile, the "best practices" for ASP.NET have been evolving. In the
beginning, most people espoused a lot of model 1 tripe. But, if you
look at the ASP.NET example apps, you can see a steady evolution away
from Model 1 toward Model 2.

It's also important to note that ASP.NET "best practices" are strongly
influenced by vendors seeking product lock-in. I think given a choice,
the "truthiness" many of ASP.NET  best practices (like use stored
procedures for absolutely everything) would evaporate in a cloud of
pixie dust.

When espousing best practices, it's also important to note that there
is a signficant difference between knocking-off a five-page
application for an intranet and engineering a 500-page public-facing
application that must serve hundreds of thousands of clients. Sure, we
all wish there was a unified theory of web development, but I think we
are about as close to that as our friends in the Physic departments
who ponder an "elegant universe".

-Ted.

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


Mime
View raw message