-Re: DISCUSS: Hive language manual to be source control managed
Edward Capriolo 2013-09-02, 15:35
I understand your concerns, but....
"Last year I converted the entire Language Manual to xdocs, but the project
died from lack of community interest."
I believe I converted a majority of the wiki before you did
but that is splitting hairs :)
"That said, I want to ask: is this the best use of the development
community's time? Some of your complaints about the wikidocs are just
glitches in the non-display versions, and presumably those can be fixed or
I have made several complains over the past few weeks about the display
versions not looking right, and no one seems to be fixing them. The fact
that the links are broken and have been for some time shows a complete lack
of care from all parties.They should have never been broken in the first
place, if you are making an edit and your not careful enough to test the
page after, that is a bad job, (no offence but sorry). If no one is
watching the edits (I am not) we are not doing a good job either.
"Also, the xdocs weren't removed deliberately -- they broke in December (
HIVE-3896 <https://issues.apache.org/jira/browse/HIVE-3896>) and no one had
the time or inclination to fix them. Has that situation changed? "
So the xdocs are broke, the wiki is broke, notice a disturbing trend here?
Think about what new users thing when they find out language manual. If I
was a new user and I looked at the wiki, I would just assume that hive was
done by a bunch of cowboy coders, and I probably would not even bother
using it because if someone's main documentation has that many broken links
the software is probably just as bad.
When we originally did the xdoc thing, no one gave a very solid reason as
to why even though reviewing and submitting a patch which usually takes 2
weeks of man hours, and unit tests that take 15 hours to run, that spending
20 minutes writing xdocs was a "great burden".
I think the situation is very different now, as I mentioned we have about
100% turnover in active comitters, Of the active committers hive/hcatalog
there is myself and Alan Gates (think pig book, hive book) we can easily
vote you on as a committer because you have shown a dedication to help with
the documentation situations (committers do not have to be coders).
The argument that killed the xdocs before was "wiki is the status quo".
That argument has clearly fallen apart. We need a better system then
'optimistically hoping that someone maintains the wiki'.
On Mon, Sep 2, 2013 at 5:06 AM, Lefty Leverenz <[EMAIL PROTECTED]>wrote:
> Last year I converted the entire Language Manual to xdocs, but the project
> died from lack of community interest. So if this goes forward, please
> don't start from scratch again -- my files would need to be updated, but
> wiki page history makes that fairly easy. Of course there are several new
> docs which would have to be converted from wiki markup to xdocs.
> That said, I want to ask: is this the best use of the development
> community's time? Some of your complaints about the wikidocs are just
> glitches in the non-display versions, and presumably those can be fixed or
> worked around. Adding and improving the content seems crucial, but why not
> do that in the wiki?
> Also, the xdocs weren't removed deliberately -- they broke in December (
> HIVE-3896 <https://issues.apache.org/jira/browse/HIVE-3896>) and no one
> had the time or inclination to fix them. Has that situation changed?
> -- Lefty Leverenz, devil's advocate
> On Sun, Sep 1, 2013 at 5:47 PM, Edward Capriolo <[EMAIL PROTECTED]>wrote:
>> I am not sure about BNF. Hive uses antlr so the language itself is never
>> described as BNF. Maybe antlr has a tool or clever way to turn the .g file
>> into BNF. If it is possible that should be something we do during a
>> document generating step. Also if a new feature does change the language
>> the theory would be the feature would not be committed unless it had