[OT] documentation versions [was Re: actionservlet init-params]

[Laurie Harper <la...@holoweb.net>]

Wendy Smoak wrote:
> Keep in mind, however, that the "official" online website actually comes 
> from the current source code, so it will diverge from the documentation 
> for the latest GA release as changes are made.
> 
> You may find things online that do not apply to your version of Struts, 
> which is why you should install the struts-documentation.war locally and 
> refer to it if you need the exact docs for your version.

I've always found this a bit odd (and it's by no means a Struts-only 
thing!) -- wouldn't it make more sense for the online documentation to 
correspond to the current release and clearly seperate documentation 
covering unreleased features? That way, the web site is a current reference 
(as opposed to a 'future reference') which ought to reduce user confusion 
("the docs say XXX but it doesn't work with the release I downloaded...")

The trouble is, different projects have different conventions for 
publishing the documentation corresponding to particular releases. Struts 
includes a struts-documentation.war; some projects have release-specific 
sections on the web site; some bundle static HTML in the release download; 
etc.)

So, the right place to look for reference documentation on release X of 
package Y is... err... well, not obvious for most Y... Sorry, just a pet 
peeve of mine ;-)

L.
-- 
Laurie, Open Source advocate, Java geek and novice blogger:
http://www.holoweb.net/laurie


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

Re: [OT] documentation versions [was Re: actionservlet init-params]

[Ted Husted <te...@gmail.com>]

Initiatives like Maven [http://maven.apache.org/] are trying to
provide a standard development and publication environement for open
source projects, but many of us still insist on going our own way.
Nature of the beast, I suppose. :)

Between 1.0.2 and 1.1.0, we did flip-flop and post the GA
documentation on top and put a link to the dev documentation down
below, but only because it was taking so long to ship 1.1.

After 1.1 shipped, we went back to publishing the dev documentation.
The big reason for this is peer review. As we make changes to the dev
release, we can post the updated documentation, for review and
comment. So, we flipped back to publlishing the dev site and docs.

Personally, I do think it would be great if we had a documentation
portal page, like httpd.apache.org uses

* http://httpd.apache.org/docs-project/

That provided a link to the 1.2.7 documentation and another to the
nighly build. Then when a 1.3.0 alpha is released (Go, James, Go),
then we could have links to 1.2.7, 1.3.0, and the nighly build.

Once upon a time, this would have been harder to do, but we've been
slowly refactoring the web site, and now there is a clearer division
between the top-level website and the documentation area for Struts
Core.

-Ted.

On 7/16/05, Laurie Harper <la...@holoweb.net> wrote:
> Wendy Smoak wrote:
> > Keep in mind, however, that the "official" online website actually comes
> > from the current source code, so it will diverge from the documentation
> > for the latest GA release as changes are made.
> >
> > You may find things online that do not apply to your version of Struts,
> > which is why you should install the struts-documentation.war locally and
> > refer to it if you need the exact docs for your version.
> 
> I've always found this a bit odd (and it's by no means a Struts-only
> thing!) -- wouldn't it make more sense for the online documentation to
> correspond to the current release and clearly seperate documentation
> covering unreleased features? That way, the web site is a current reference
> (as opposed to a 'future reference') which ought to reduce user confusion
> ("the docs say XXX but it doesn't work with the release I downloaded...")
> 
> The trouble is, different projects have different conventions for
> publishing the documentation corresponding to particular releases. Struts
> includes a struts-documentation.war; some projects have release-specific
> sections on the web site; some bundle static HTML in the release download;
> etc.)
> 
> So, the right place to look for reference documentation on release X of
> package Y is... err... well, not obvious for most Y... Sorry, just a pet
> peeve of mine ;-)
> 
> L.
> --
> Laurie, Open Source advocate, Java geek and novice blogger:
> http://www.holoweb.net/laurie

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