Recently a JIRA was opened in Hive to move some of the Hive documents from wiki to version control ( https://issues.apache.org/jira/browse/HIVE-3039 ). Edward commented on the JIRA:
>>>This issue was opened and died a long time ago. After I moved the >>>documentation from the wiki to the source everyone refused to update it and >>>it was a dead issue. I would advice not going down this very frustrating >>>path again. ... I marked pages on the wiki that I moved as 'DO NOT EDIT THIS PAGE THIS IS NOW IN XDOCS'. People ran into this and complained they explicitly did not want to use in line documentation. You can find the history on the mailing list.<<< The value of version specific documentation is very clear to me (and apparently to others since I cannot think of a single large project that does not do it), so I am trying to figure out if Hive is really opposed to it or just wants to keep the wikis open. I've been going over the old JIRAs and mailing list archives as Edward suggested to understand what the decision at the time was. Here's what I have found. The initial approach was covered in the notes from the July 2010 Hive contributor meetup ( https://cwiki.apache.org/confluence/display/Hive/Development+ContributorsMeetings+HiveContributorsMinutes100706 ): >>> • There was a discussion about the plan to move the documentation off of the wiki and into version control. • Several people voiced concerns that developers/users are less likely to update the documentation if doing so requires them to submit a patch. • The new proposal for documentation reached at the meeting is as follows: • The trunk version of the documentation will be maintained on the wiki. • As part of the release process the documentation will be copied off of the wiki and converted to xdoc, and then checked into svn. • HTML documentation generated from the xdoc will be posted to the Hive webpage when the new release is posted. • Carl is going to investigate the feasibility of writing a tool that converts documentation directly from !MoinMoin wiki markup to xdoc. <<< There was some email discussion generated by these notes which did not change the general view: http://mail-archives.apache.org/mod_mbox/hive-dev/201007.mbox/%3CAANLkTin3EWUKWj65ZzDApGlrEEWYyg9sVrgGzDaFWO7T%40mail.gmail.com%3E In a later email thread Joydeep rather forcefully argued that the wiki pages should be left open even though there are xdocs: http://mail-archives.apache.org/mod_mbox/hive-dev/201008.mbox/ajax/%3CB4F4475C5A97594A87B283C91F9E873A017FB35F%40sc-mbx05.TheFacebook.com%3E Then in August it appears it was discussed again with the outcome that docs should still be kept in source control ( https://cwiki.apache.org/confluence/display/Hive/Development+ContributorsMeetings+HiveContributorsMinutes100808 ): >>> Discussed moving the documentation from the wiki to version control. • Probably not practical to maintain the trunk version of the docs on the wiki and roll over to version control at release time, so trunk version of docs will be maintained in vcs. • It was agreed that feature patches should include updates to the docs, but it is also acceptable to file a doc ticket if there is time pressure to commit.j • Will maintain an errata page on the wiki for collecting updates/corrections from users. These notes will be rolled into the documentation in vcs on a monthly basis. <<< Also relevant are the two older JIRA issues covering the abortive move: https://issues.apache.org/jira/browse/HIVE-1135 https://issues.apache.org/jira/browse/HIVE-1446 It appears to me that there was lack of clarity about how to move information from the wiki to the version controlled doc. There was also opposition expressed to locking off the wiki. As far as I can tell no one was opposed to version control of the docs per se. So, I propose we let this, and similar patches that propose version specific docs in version control, go forward. There's no need to close off the wiki. There will be a tax on developers of features to add docs if they want users to know about them. But this seems to me a good thing rather than a bad thing. Thoughts? Alan.
