On Thu, Jul 15, 2010 at 5:15 AM, Carl Steinbach <c...@cloudera.com> wrote: > Hi, > > Notes from the last Hive Contributors Meeting are now available on the > wiki: http://wiki.apache.org/hadoop/HiveContributorsMinutes100706 > > Thanks. > > Carl >
Sorry I did not get to listen to the event. So one topic of interest for me is: "Several people voiced concerns that developers/users are less likely to update the documentation if doing so requires them to submit a patch." I think this is a valid concern, however I want to point out a few bigger picture things. First, I want to point out what I think is a great shining of documentation. http://hornetq.sourceforge.net/docs/hornetq-2.1.1.Final/user-manual/en/html/index.html hbase does a nice job as well. http://hbase.apache.org/docs/r0.20.5/metrics.html While I think the hive documentation on the wiki is better then most wiki's, it has some issues. Here is an example. I am running hive5. So a user is running hive and reads the wiki, and says "Wow we have view support, let me try this" This fails because views are only in trunk. This gives people a general bad impression about hive because they expect trunk features, because they have no authoritative documentation on THEIR VERSION. Users can be fickle and if they hit incorrect documentation they start to get the impression the software is "buggy" suddenly they start questioning everything and bringing every problem to the hive administrator because even though they wrote a query wrong their first instinct is to "blame hive". I find editing xdocs EASIER then working with wiki. Wiki is great and all but in my travels I have to work on 5 different wiki's they all are slightly different in what they support and their mark up. We should be able to commit xdoc patches without full unit tests. Keeping the xdoc up to date should not be an issue because we should simply not accept a patch that changes/adds functionality without some xdoc. Another issue right now is there are features that are NOT documented anywhere. When a user asks about those features I have to send them to Jira tickets, often times the ticket will have a long back and forth where the feature is debated, or sometimes just a patch, you never see the full syntax, it can be very confusing,I often end up telling them to dig through a .q file inside a patch to figure out what this feature is and how to use it. While most people are good about updating the wiki we know that things tend to fall though the cracks. I think there is still a place for wiki, free form, multi-person planning, etc but I do not think a mature software product can every have authoritative documentation in a wiki.
