hive-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Alan Gates <ga...@hortonworks.com>
Subject Version specific Hive docs
Date Thu, 27 Sep 2012 00:41:05 GMT
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.
Mime
View raw message