On Tue, May 12, 2009 at 9:41 PM, Robert Burrell Donkin <[email protected]> wrote: > On Tue, May 12, 2009 at 5:51 PM, Eric MacAdie <[email protected]> wrote: >> Robert Burrell Donkin wrote: >>> >>> On Sun, May 10, 2009 at 8:13 PM, Eric MacAdie <[email protected]> wrote: >>> >>>> >>>> WRT documentation, I have posted a few pages about James on my site. Have >>>> a >>>> look at them and let me know if you think they might be helpful. >>>> >>>> >>>> http://www.MacAdie.net/opencms/opencms/sites/MacAdie.dot.Net/Java/James/index.html >>>> >>> >>> yep :-) >>> >>> and you're (all) right that documentation is scattered around >>> >>> the current wiki has a low barrier to entry (which is good for >>> informal documention) but the content can't be used as official >>> documentation (apache lacks the required license). this limits the >>> usefulness as far as developing consistent user documentation goes. >>> >>> added content to the website means checking out the source and using >>> maven to build it. i try to encourage contributors to do this since >>> it's the first step towards becoming a committer. but as some folks on >>> this thread have noted, it is a little fiddly and has a relatively >>> high barrier to entry. >>> >>> then again, any contributors are going to need to jump through some >>> hoops to ensure that Apache has the required license to use their >>> contributions >>> >>> one option would be to set up a confluence instance (like >>> http://cwiki.apache.org/labs/clouds.html) for an official content - >>> user guide, perhaps. contributors would need to have a CLA on file >>> (this agreement grants apache the license required to distribute with >>> a release). the contents would be exported and included with future >>> releases. >>> >>> would anyone be interested in writing documentation on confluence? >>> >>> - robert >>> >> >> Sure, I would be interested in writing documentation on confluence. > > great :-) > > if you haven't got a CLA on file for apache then the first step is to > do that (see http://www.apache.org/licenses/#clas) > > (i'll take a look at getting the confluence instance sorted out)
james has a confluence instance at http://cwiki.apache.org/JAMES/ which looks to be used only for experimentation. i'd like to start using it to develop higher quality user centered documentation. opinions? objections? >> I think a good place to start would be a step-by-step guide on getting >> involved with James. The URL for the "Get Involved" link on the James site >> is http://jakarta.apache.org/site/getinvolved.html, which redirects to >> http://www.apache.org/foundation/getinvolved.html. And maybe this is >> redundant, but a few pages/cheat sheets within James about svn and maven >> with a few basic commands to get started would be good. I have little >> experience with svn or maven, so reading that I have to go out and learn >> several other things just to do the one thing I want is a bit off-putting. >> But that is just me. > > a cheat sheet sounds like a good idea > > and yes, the project level documentation could probably do with > revising (this thread is getting a little long and we're drifting OT > so i'll branch a new one) perhaps it would be a good idea to simplify the menu a good start would be consolidate the "Useful Information" and "Foundation" menu elements: > Apache Software Foundation > * Get Involved > * FAQ > * Sponsorship > * Donations > * Thanks the japanese translation looks out of date so let's drop "Translation" James has no unstable releases so let's drop that perhaps Contributing should be renamed Contributor's Guide and have Standards content merged in we don't seem to use the wiki much any more so maybe that needs some thinking about in terms of content, the page probably works much better from the perspective of a developer looking for a library than a user. the product list is also outdated. may want to split products into Applications and Libraries menus on the left. opinions? - robert --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
