Well, there is a link to the upgraders wiki page in the Release Notes, so it's "incorporated by reference." I added a bullet to help emphasize the link.
One reason the content on the updgrader pages is so useful is because it's easy for developers to update it. The other documenation is kept in XML, and if we changed the format, we'd probably reduce feedback. Likewise, if we put some of it under XML, we'd end up with two versions of the page to manage. Projects like WebWork and Geronimo, among others, have been experimenting with making wiki docs the "first-class documentation" that is bundled with the distribution. Wiki's like Confluence have some nice export capabilities, which opens the door to exporting the wiki into HTML. Geronimo is experiment with continuous automatic exports of Confluence pages, so that we can have the beneifts of a wiki and the efficiency of static HTML. WebWork/Action2 also uses a "snippet" macro to incorporate text from Javadocs and example programs directly into the wiki pages. I'm a big fan of this idea, since it will let us dual-use some of the very excellent Javadocs we already have. The big downside right now is that Confluence edits are atomic to each page. We can't make batch updates, which creates a lot of email churn when making sweeping changes. Instead of one email overviewing changes to a dozen pages, we all get a dozen individual emails :( There's also ongoing work in backing a wiki with Subversion, so that you could commit changes from the SVN CLI or TortoiseSVN, instead of plowing through the web interface. In the meantime, yes, we should continue to look for places where we can cross-reference the wiki with the static documentation and try to make sure those links are as visible as possible. But, we would want to be careful what we move from the wiki to the static pages, since the static pages are harder to maintaine. -Ted. On 5/16/06, Paul Benedict <[EMAIL PROTECTED]> wrote:
I think it would be a good idea if we either linked or transfered some content from the Wiki pages to the user guide. For instance, I just read the upgrade notes on 1.2.9 on the wiki and it is fabulous. Those kind of things should be first-class documents in our website. Any thoughts about this proposal?
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
