On Wed, 26 Jun 2002, Ted Husted wrote:
> Date: Wed, 26 Jun 2002 19:44:48 -0400
> From: Ted Husted <[EMAIL PROTECTED]>
> Reply-To: Struts Developers List <[EMAIL PROTECTED]>,
> [EMAIL PROTECTED]
> To: Struts Developers List <[EMAIL PROTECTED]>
> Subject: Re: Planning for 1.1 beta 2
>
> For the docs, do you think it might be useful to add a new 1.1 section
> and march through the new features there, rather than patch the 1.0
> docs?
>
I think a "whats new" tour in the release notes is certainly useful, but
I'm not sure it makes sense to segregate the new stuff elsewhere. For
example, in the building_controller.xml page, it makes sense to talk about
the new exception handling options.
> A 1.1 section might be easier to create, since we won't have to worry
> about segues, and will do double-duty as an upgraders guide. Of course,
> we could still go back and put in references to the 1.1 features in the
> appropriate places int the 1.0 chapters. Just thinking it might be
> easier if we don't have to fuss with splicing the narrative.
>
> Generally, I'd like to try and start reusing more of the JavaDocs in the
> User Guide. It seems to me that the User Guide should organize the
> presentation of the classes and add usage examples, but that our
> (meaning mostly Craig's =:0) JavaDocs are so good, maybe we should
> cutting and pasting more of those over,
or linking to them, since we know where the JavaDocs are compared to the
user's guide.
> rather than writing the same
> thing in different words. Long term, this would also help keep things
> synched, since it would be easier to conform the guide to the JavaDocs
> (and vice versa). More like what we did with the Developers Guides, I
> guess, except that there would one(s) for the Action, Config, and Util
> classes.
>
I'm pretty happy with how it worked out to double-duty the tag library
developer's guides. The package.html for the non-tag-library packages
could serve the same role for the Java programmer -- with the added
benefit that even people who don't read documentation often look at the
JavaDocs, so they have a better chance of seeing this stuff.
> I don't want to get into that for the 1.0 User Guide now, but we could
> start on that path for the 1.1 chapter, and see how it goes.
>
Agreed -- I don't think we need to do anything other than critical
bugfixes in 1.0.
> Meanwhile, I've set up a "diff" section in the release notes with
> pointers to every thing with 1.1 features or deprecations, that could
> then be used to help create the 1.1 doc section.
>
> http://jakarta.apache.org/struts/userGuide/release-notes.html#diff
>
> AFAIK, the JavaDocs are all updated with @since 1.1's now, and refer to
> execute rather than perform, and so forth. The ActionServlet docs may
> need to expand on the new flow, but otherwise we seem to be good on the
> JavaDoc front. The next thing I was going to do was finish-up on the
> release notes, so that everything linked in the diff section is
> mentioned above, and maybe trundle through the CVS mail log.
>
Someplace, we definitely need discussions of dynamic form beans (probably
in the building-the-view page) and sub-applications (either an expansion
on "configuring the controller" or perhaps a page on advanced topics or
some such.
> -T.
>
Craig
> James Holmes wrote:
> >
> > +1 and more than happy to help with bugs and docs.
> >
> > -james
> > [EMAIL PROTECTED]
> > http://www.jamesholmes.com/struts/
>
> --
> To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
>
>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
