On Dec 6, 2012, at 4:27 AM, Brock Noland wrote:
> At present I feel like our documentation is split half way between the
> wiki and the website. What are the guidelines as to what goes on the
> wiki vs the website?
> FWIW, I am fan of the MRUnit website(http://mrunit.apache.org/). Note
> that I did not create it! :) It has the "How to Release", "How to edit
> the website", right on the website itself. Updating it is not very
> hard because MRUnit uses CMS as Flume does.
The issue is about control. The wiki is supposed to be open for anyone to edit while the web site can only be updated by committers. I've said several times that I'm not a fan of having the user's guide and developer's guide in the source code. I would much prefer that they are directly on the web site and edited in the CMS.
One thing I don't care for in the mrunit site is that some of the site content is on the wiki. I am not a fan of web sites that have you click on a link and you are somewhere else and all the site navigation is gone. If they want to show wiki content they should do it in an iframe.
Although I developed the web site in RST I did that because that is what was chosen for the User's Guide and Developer's Guide. It wasn't really designed to develop web sites although it does a decent job. Personally, I'd convert all of it to something more CMS friendly which is also compatible with the Maven PDF plugin so it is easy to generate the guides from the CMS content at any time.