-Re: DISCUSS: Hive language manual to be source control managed
Lefty Leverenz 2013-09-05, 05:38
> I believe I converted a majority of the wiki before you did
> 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
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
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
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
On Wed, Sep 4, 2013 at 7:37 PM, Alan Gates <[EMAIL PROTECTED]> 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.
> 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
> > 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-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
> > 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