Robert Burrell Donkin wrote: > 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?
+1 Bernd --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
