Martin Cooper wrote: > > ----- Original Message ----- > From: "Ted Husted" <[EMAIL PROTECTED]> > To: "Struts Developers List" <[EMAIL PROTECTED]> > Sent: Monday, January 21, 2002 3:52 AM > Subject: Re: Struts Next > > > Right now, we're exploding the struts-documentation WAR to create the > > Web site. > > Having worked with the Anakia way (a la commons and site2) a little bit now, > I have to say that I like that web site update process much better than our > exploding war file. It's simpler and quicker. I wonder what other folks > think about migrating to this process at some point? > > This would also release us from the one-to-one mapping we currently have > between what's bundled with the release (i.e. struts-documentation.war) and > what's on the public web site. (See below.)
I don't think it's really an "Anakia" issue, just a matter of whether we check in the html files that are generated by the Digester, and then check those out again at the Web site. Something that I set up for myself is a build-website target in the build.xml. With that and a build-doc script and batch file, we'd be at the same place site2 is. But then there would be a definite 1:1 mapping between the nightly build and the current website, unless we set it to check out a branch, but that seems like a long term maintenance hassle. It is standard practice for web site to be packaged with a product like this. I think the relationship between the web site and the stuts-documentation is that we are packaging the web site as the struts-documentation. > > We've been trying to keep the latest release front-and-center, mainly > > because we seem to have a large base of professional teams that cannot > > use unreleased software. > > And I think we should continue to do that. Otherwise, we'll go back to the > endless questions on struts-user about why something documented on the web > site (for the nightly build) doesn't work (because the user is using the > released build). > > > How about if we start to carry a copy of the documentation for the > > latest formal release -AND- the nighly build on the Website. The nightly > > build could be on top, but have an absolute link to the documentation > > for the prior release on the Website > > (jakarta.apache.org/struts/1.0.1/...). This way people who want to scope > > the current release first (since that's the one they would have to > > propose today), can get easy access to that, but we still have the > > latest and greatest out-front. > > I'm definitely +1 on carrying full documentation for both the latest > "official" release and the nightly build on the web site. I'm not so sure > about having the nightly build docs on top (see comments above), but I think > if we can make it sufficiently obvious as to what's what, it shouldn't > matter too much. To make it "sufficiently obvious", we could consider ideas > such as graphics to distinguish the two, or (probably more workable) making > neither available on the top level page, but having separate links to the > comprehensive docs for each version. It's mainly a "News and Status" thing. I'd like to add a News page (see nightly build), but logically that should be the latest news, not a news snapshot from the last release. This implies that the nightly build docs should be on top. I'd like to do it the other way around too, but it start to get very kludgy when you think about things would flow from release to release. If we have the web site for a prior release parked in a subdirectory, then it's very easy for the nightly build to link back to 1.0, and 1.0.1, and so forth. But yes, we could change the home page so that there were very obvious links from the nightly build web site to the documentation (e.g. web site) for the prior releases. I do think a 1:1 relationship between the documentation and the web site is a good thing, since they really should be the same thing. > One other point here, related to my earlier comments about the one-to-one > mapping. While the web site should contain docs for both current release and > nightly versions, I think it would be a good idea for the > struts-documentation.war web app to contain *only* the docs for that > version. I don't see a need for that part of the binary download to contain > docs for multiple versions, and I suspect that simplifying the docs web app > will also help users to understand what exactly they have downloaded. Agreed. I was just thinking that when the release came out, we'd create a subdirectory on the site, explode the docs for the release under that, and then hyperlink to that from the nightly build. If they used the nightly build offline, the hyperlink would be to jakarta.apache.org, not relative to the war. > Putting this together with the use of Anakia to generate the web site > content could simplify things considerably, since we should then be able to > use CVS tags to manage our docs and our web site more easily. > > > We also need to be scrupulous about marking new code and documentation > > with @since statements. I've started to fix these as I find them, and > > will continue to do so. > > Although perhaps less useful if we have separate complete docs for release > and nightly, it would also be useful to have the taglib docs indicate when > tags (and even individual attributes) were first introduced. I think it is very important that we document when features are added, in the code, in the Users Guide, and in the taglibs XMLs. This is very helpful when you upgrade, since you can look for the since 1.x markers. > > I've got a start on the release notes, and then will look updating the > > User Guide from those. > > > > I've also started a News and Status page in the nightly build, and will > > continue to work on that. This will supply the material for the new > > Jakarta newsletter. > > Sounds good! > > -- > Martin Cooper -- Ted Husted, Husted dot Com, Fairport NY USA. -- Java Web Development with Struts. -- Tel +1 585 737-3463. -- Web http://www.husted.com/struts/ -- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
