We're not communicating well--I blame OOPSLA. In a nutshell, I'm saying:
# Yes, remove examples from Javadocs. # No, keep "blessed" examples in source control... # ...as existing or new test cases (Java/JSP/FreeMarker [1])... # ...that can be pulled into the wiki via snippets. # Additional examples can still be added/etc. by non-committers. Dave [1] I'll work on the snippet macro/etc. (if necessary) to support what I want to do. --- On Thu, 10/23/08, Philip Luppens wrote: > From: Philip Luppens <[EMAIL PROTECTED]> > Subject: Documentation issues (was: Re: Concerned Strutszien: A Manifesto) > To: "Struts Developers List" <dev@struts.apache.org>, [EMAIL PROTECTED] > Date: Thursday, October 23, 2008, 1:48 AM > On Thu, Oct 23, 2008 at 1:03 AM, Dave Newton > <[EMAIL PROTECTED]> wrote: > > --- On Wed, 10/22/08, Philip Luppens wrote: > >> Javadoc makes a very poor format for creating > example code; > > > > Not in JavaDoc, as Java/JSP/FreeMarker/etc. and pulled > in to the wiki via snippets. That way they're examples > that actually work. > > > > Not sure I'm following: what I meant are snippets of > code and > configuration being declared in the javadoc like this: > /** > * <!-- start snippet example --> > * <foo> > * <bar> > * <!-- invalid example key --> > * message['key'] = invalid; > > ... etc. Readability is less than optimal (esp. compared to > the pure > wiki variant), and I doubt this approach will keep the code > in touch > with the documentation. If there are many people looking at > the > examples, then problems will be spotted swiftly, and > someone who filed > a CLA can log in and make the changes, see the preview, and > save the > pages. If they're watching the page, they'll be > notified, we can leave > a comment, etc. If we want to correct a mistake in an > example pulled > from the repository, it goes like this (at least for me): > Spot a > comment on a page telling us that an example contains wrong > or > outdated code. Click to edit the page, discover the example > is being > pulled from the svn. If we have an IDE/svn client, fire it > up, check > out the source file, and make the change, commit it, go > back to the > page, verify it is looking correctly, sacrifce a goat to > hope the > snippet actually gets updated (I'm not sure it's > seen as a new > 'version' if a snippet gets changed and reloaded - > can anyone verify ? > - that would explain why some of the static pages are so > outdated), > and comment on the user comment that the code was changed. > Ugh. I'll > take a quick edit of the wiki page over that any time of > the day. It > looks better and it works faster. > > Note: I'm not talking about the inclusion of internal > code and/or > configuration files like 'struts-default.xml'. But > those cases are > very limited. > > Phil > > > Dave > > -- > "We cannot change the cards we are dealt, just how we > play the hand." > - Randy Pausch > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [EMAIL PROTECTED] > For additional commands, e-mail: [EMAIL PROTECTED] --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
