cassandra-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Jack Krupansky" <j...@basetechnology.com>
Subject Re: Why is the cassandra documentation such poor quality?
Date Wed, 23 Jul 2014 12:52:02 GMT
I do recall seeing your announcement of your driver, but I think it got lost in the discussion
of whether it supported CQL. If you say it supports CQL and native protocol, I’m sure it
will get very prompt attention.

-- Jack Krupansky

From: Peter Lin 
Sent: Wednesday, July 23, 2014 8:30 AM
To: user@cassandra.apache.org 
Subject: Re: Why is the cassandra documentation such poor quality?


I sent a request to add a link my .Net driver for cassandra to the wiki over 5 weeks back
and no response at all.


I sent another request way back in 2013 and got zero response. Again, I totally understand
people are busy and I'm just as guilty as everyone else of letting requests slip by. It's
the reality of contributing to open source as a hobby. If I wasn't serious about contributing
to cassandra community, I wouldn't have spent 2.5 months porting Hector to C# manually.


Perhaps the real cause is that some committers can't "empathise" with others in the community?





On Wed, Jul 23, 2014 at 8:22 AM, Benedict Elliott Smith <belliottsmith@datastax.com>
wrote:

  All requests I've seen in the past year to edit the wiki (admittedly only 2-3) have been
answered promptly with editing privileges. Personally I don't have a major preference either
way for policy - there are positives and negatives to each approach - but, like I said, raise
it on the dev list and see if anybody else does. 

  However I must admit I cannot empathise with your characterisation of requesting permission
as 'begging', or a 'slap in the face', or that it is even particularly onerous. It is a slight
psychological barrier, but in my personal experience when a psychological barrier as low as
this prevents me from taking action, it's usually because I don't have as much desire to contribute
as I thought I did. 





  On Wed, Jul 23, 2014 at 1:54 PM, Peter Lin <woolfel@gmail.com> wrote:


    I've submitted requests to edit the wiki in the past and nothing ever got done.


    Having been an apache committer and contributor over the years, I can totally understand
that people are busy. I also understand that "most" developer find writing docs tedious.


    I'd rather not harass the committers about wiki edits, since I didn't like it when it
happened to me in the past. That's why many apache projects keep their wiki's open. Honestly,
as much as I find writing docs challenging and tedious, it's critical and important. For my
other open source projects, I force myself to write docs.


    my point is, the wiki should be open and the barrier should be removed. Having to "beg/ask"
to edit the wiki feels like a slap in the face to me, but maybe I'm alone in this. Then again,
I've heard the same sentiment from other people about cassandra's wiki. The thing is, they
just chalk it up to "cassandra committers don't give a crap about docs". I do my best to defend
the committers and point out some are volunteers, but it does give the public a negative impression.
I know the committers care about docs, but they don't always have time to do it.


    I know that given a choice between coding or writing docs, 90% of the time I'll choose
coding. What I've decided instead is to document stuff on one of my blogs.  If someone gets
lucky, maybe google will return the result. I keep asking myself "what's the point of closing
a wiki?"


     



    On Wed, Jul 23, 2014 at 7:40 AM, Benedict Elliott Smith <belliottsmith@datastax.com>
wrote:

      It only takes a moment to ask to be added as a wiki contributor; if you email the dev
list or ask on irc, somebody with privileges will ordinarily add you within a day. It may
be a psychological barrier, but it isn't really a practical one. Still, if you feel the policy
is incorrect, raise this on the dev list also.



      On Wed, Jul 23, 2014 at 1:33 PM, Peter Lin <woolfel@gmail.com> wrote:


        I've tried to contribute docs to Cassandra wiki in the past, but there's an obstacle.


        currently wiki.apache.org/cassandra is locked down, so only commiters can edit it.
I really wish that wasn't the case, since it wastes time. the commiters are busy writing code.
Having to email a commiter and ask them to update it feels silly to me and kind of goes against
openness. Back when I was active with JMeter, we decided to leave it open so that anyone can
edit the docs.


        I can't be the only one that wants to help make the docs better, but get frustrated
with the wiki being closed.





        On Wed, Jul 23, 2014 at 4:25 AM, <spawgi@gmail.com> wrote:

          I would like to help out with the documentation of C*. How do I start?




          On Wed, Jul 23, 2014 at 12:46 PM, Robert Stupp <snazy@snazy.de> wrote:

            Just a note:
            If you have suggestions how to improve documentation on the datastax website,
write them an email to docs@datastax.com. They appreciate proposals :)

            Am 23.07.2014 um 09:10 schrieb Mark Reddy <mark.reddy@boxever.com>:


              Hi Kevin,

              The difference here is that the Apache Cassandra site is maintained by the community
whereas the DataStax site is maintained by paid employees with a vested interest in producing
documentation. 

              With DataStax having some comprehensive docs, I guess the desire for people
to maintain the Apache site has dwindled. However, if you are interested in contributing to
it and bringing it back up to standard you can, thus is the freedom of open source. 


              Mark



              On Wed, Jul 23, 2014 at 2:54 AM, Kevin Burton <burton@spinn3r.com> wrote:

                This document:

                https://wiki.apache.org/cassandra/Operations


                … for example.  Is extremely out dated… does NOT reflect 2.x releases
certainly.  Mentions commands that are long since removed/deprecated.

                Instead of giving bad documentation, maybe remove this and mark it as obsolete.

                The datastax documentation… is … acceptable I guess.  My main criticism
there is that a lot of it it is in their blog. 

                Kevin


                -- 


                Founder/CEO Spinn3r.com

                Location: San Francisco, CA

                blog: http://burtonator.wordpress.com
                … or check out my Google+ profile








          -- 
          http://spawgi.wordpress.com
          We can do it and do it better. 





Mime
View raw message