> > I believe I converted a majority of the wiki before you did > https://github.com/mislam77/hive-li/blob/master/docs/xdocs/language_manual/cli.xml, > but that is splitting hairs :)
Go ahead and split hairs, Edward, because you deserve plenty of credit. And last year you warned me that the community would resist converting to xdocs. Has the time finally come to push this initiative through to completion? Let me split another hair: "my" converted files actually belong to Hortonworks, and Alan deserves credit for assigning that task to me (thanks, Alan). I'd better return the files so they can contribute them. What about Dean's suggestion of using Github Pages? Any other opinions? I'll take a look at Github Pages, and the first thing I want to know is whether a commit stage is required. For xdocs, commits were a bottleneck. That's why I asked if this is a good use of the community's time ... plus, I enjoy the raw power of making changes in the wiki without adult supervision. Bwa-ha-ha! If we get more tech writers involved, such as Ellen Evans who just got edit access, then it might be helpful to have some writers be committers for xdocs or any doc system with commits. But multiple writer-committers would be better than just one, since self-commits are frowned upon (except in psychiatric cases). The second thing I'll look at in Github Pages is how they do version control. A problem with requiring documentation in the wiki before committing a new feature is that the documentation appears before the code is released. When docs are released with the code, like xdocs, that's not a problem. -- Lefty On Wed, Sep 4, 2013 at 7:37 PM, Alan Gates <ga...@hortonworks.com> wrote: > I'm definitely +1 on moving the language doc to source control. Being > able to have versions of the language manual that match versions of Hive > would be very valuable. > > Alan. > > > On Sep 1, 2013, at 2:39 PM, Edward Capriolo wrote: > > > Over the past few weeks I have taken several looks over documents in our > wiki. > > The page that strikes me as alarmingly poor is the: > > https://cwiki.apache.org/Hive/languagemanual.html > > > > This page has several critical broken links such as > https://cwiki.apache.org/Hive/languagemanual-groupby.html > > https://cwiki.apache.org/Hive/languagemanual-transform.html > > > > The language manual used to be in decent shape. At times it had > omissions or was not clear about what version something appeared it, but it > was very usable. > > > > A long time ago I had began and completed moving the wiki documentation > inside the project as xdoc. After completion, several had a problem with > the xdocs approach. The main complaint was the xdoc approach was too > cumbersome. (However we have basically had a 'turn over' and since that > time I am one of the few active committers) > > > > The language manual is in very poor shape at the moment with broken > links, incorrect content, incomplete content, and poor coverage of the > actual languages. IMHO the attempts to crowd-source this documentation has > failed. Having a good concise language manual is critical to the success > and adoption of hive. > > > > I do not believe all of our documentation needs to be in xdoc (as in > every udf, or every input format) but I believe the language manual surely > does. > > > > Please review the current wiki and discuss the concept of moving the > language manual to source control, or suggest other options. > > > > Thank you, > > Edward > > > > > > > -- > CONFIDENTIALITY NOTICE > NOTICE: This message is intended for the use of the individual or entity to > which it is addressed and may contain information that is confidential, > privileged and exempt from disclosure under applicable law. If the reader > of this message is not the intended recipient, you are hereby notified that > any printing, copying, dissemination, distribution, disclosure or > forwarding of this communication is strictly prohibited. If you have > received this communication in error, please contact the sender immediately > and delete it from your system. Thank You. >
