I'm not sure I understand the issue around only having people who have file CLAs updating documentation. Anyone can create anything they want on a wiki. However, I would recommend against having formal documentation on the wiki for exactly that reason.
Is there a reason not to use the Maven site plugin and generate documentation on the web site? I also have no problem with recommending the use of a CMS. Ralph On Jul 19, 2011, at 3:04 PM, Tom White wrote: > I agree with Patrick. Having the docs under version control and a part > of the release is preferred. > > Tom > > On Tue, Jul 19, 2011 at 2:54 PM, Patrick Hunt <ph...@apache.org> wrote: >> I'd advise against this. Only people with filed CLAs can be allowed to >> commit to your docs, also the PPMC must review each change - currently >> they are in svn, if you move them to wiki you'll have to manage this >> issue via wiki auth. See this discussion on whirr: >> https://issues.apache.org/jira/browse/WHIRR-19?focusedCommentId=12876503&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-12876503 >> >> Whirr eventually went with mvn site generation using confluence >> markup, however I'd probably go with CMS and textile markup at this >> point (that's what we recently/currently do in ZK) >> http://www.apache.org/dev/cms.html Additional benefit is that you can >> use this for both your web site and your docs. >> >> Patrick >> >> On Tue, Jul 19, 2011 at 2:43 PM, Jonathan Hsieh <j...@cloudera.com> wrote: >>> Hey all, >>> >>> I wanted to propose that we port the current documentation from its current >>> asciidoc form to the wiki. The documentation hasn't had a major structural >>> update for a while and from some of the lessons we've learned in the past >>> year it could use a refresh. >>> >>> Here are the main trade offs that I currently have with this move. >>> >>> Pro: >>> * Documentation will be easier for more people to modify and update. >>> * The move would simplify the build -- removing dependencies on several >>> packages including asciidoc, graphviz, syntax-highilght, and suffers from >>> version incompatiblity issues across different linux/windows/mac os's. >>> * By requiring design docs for major new features in the wiki, adding them >>> to the docs will require less effort. >>> >>> Con: >>> * It will be more difficult to force code commits to make documentation >>> updates. >>> * Versioning documentation may become more of a hassle. >>> >>> Lets discuss and when it peters out we can vote. >>> >>> Thanks, >>> Jon. >>> >>> -- >>> // Jonathan Hsieh (shay) >>> // Software Engineer, Cloudera >>> // j...@cloudera.com >>> >>
