On Wed, Oct 22, 2008 at 8:45 PM, Dave Newton <[EMAIL PROTECTED]> wrote: > --- On Wed, 10/22/08, Philip Luppens wrote: >> - Documentation: no more (example) documentation in the >> Javadocs so non-committers can make changes in the wiki. > > I'd augment this a bit > > I'd really like all the examples to be in source control and have associated > tests, and I'm willing to spend some effort to do that (starting at the > beginning of 2009; this year is packed). > > Yes, that means that either non-committers can't write "official" examples, > although un-official examples would be supported--as they are now--on the > wiki. I don't see a whole lot of non-developer-driven examples, however, > although they exist. > > We're still hammered by documentation (2.0 v. 2.1 issues) and I'd *really* > like to see two Confluence spaces for that. Yeah, I know 2.1 is (in theory) > rolling soon, but not everyone may upgrade right away. I'm also willing to > put some work into that. > > I agree with one of the initial statements that the documentation could be > better organized, although I think that could be handled with some aggregate > pages that organize existing documentation in different (hopefully better) > ways. > > I also like the tags being documented through the annotations, but either the > annotations or the processing tool should include some information regarding > when attributes were introduced etc. > > Dave
At the risk of going out of scope with this discussion (there was a thread a couple of months ago about this), just some thoughts: Javadoc makes a very poor format for creating example code; esp. in combination with the escaping of tags - xml configuration for example is pretty hard to get correct on the first commit. So no, keep the best tool for the job: code examples and configuration in the wiki, the javadocs in the source code. If you really want 'official examples' then just limit the people that can edit the page. Btw, regarding the static export of pages: when looking for documentation through google, I always end up at hopelessly outdated versions - even though various newer version exists, often with corrections and new content. Very annoying and confusing for everyone consulting the documentation. Phil > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [EMAIL PROTECTED] > For additional commands, e-mail: [EMAIL PROTECTED] > > -- "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]
