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 19:56:15 GMT
Out of curiosity, did you look at or utilize DataStax’s free online training?

See:
http://www.datastax.com/what-we-offer/products-services/training/virtual-training

Any feedback? Any suggestions as to what needs it does or doesn’t fulfill?

-- Jack Krupansky

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

I think the problem is a little deeper than that. I've been working with cassandra for about
7 months now - it was very challenging to find out any real information about using cassandra,
and even harder to get clear information on operating it. There's a truckload of reading you
have to do, and no one place you can find it.  

Searching google largely turns up datastax blog posts and DSE docs, almost all of it out of
date (not to say the docs aren't up to date, but the search results often result in old docs,
and old blog posts).

Deeper searching usually results in a link to JIRA. No offense to anyone involved, but when
your first experience of trying to learn an open source tool is the realisation that all the
information you need is simply spread across ~7000 jira tickets, it doesn't make the knowledge
feel very accessible.

As an example, finding a java driver with a useful abstraction was non-trivial - it appeared
on the surface that there wasn't really one, that you had to write everything yourself on
top of CQL. Now I (as everyone else on this list knows) that datastax provide one. At the
time I never found a simple page that just pointed me in the direction, and showed a basic
usage example.

Another example is that there is constant confusion about nonclamenture on this list, because
naming has changed over time. If you don't know you're reading old information, or what the
significant changes are between 0.whatever, 1.whatever and 2.whatever its very hard to know
whether you're even googling for the right thing. Dynamic columns are a great example of this.
I think the fact that it keeps coming up on this list is a strong indicator that the information
is not available in a 'sufficient' way.

Another way of putting it is, when I started trying to learn about cassandra, pretty much
every piece of consumable information I was able to find was out of date, but it wasn't always
obvious that this was the case.

Having said all that, everything I've seen on this list points to prompt, useful and friendly
assistance, even for questions that are frequently asked. I have no stake either way in what
the rules on who can contribute are, but I can definitely say I would have very much enjoyed
a much softer landing when trying to learn cassandra, from the basics all the way through
to the detail of ops.





On 23 July 2014 21:55, Jason Wee <peichieh@gmail.com> wrote:

  I agree to the people here already sharing their ways to access documentation. If you are
starter, you should better spend time to search for documentation (like using google) or hours
to read. Then start ask specific question. Coming here kpkb about poor quality of documentation
just does not cut it.  

  If you find documentation is outdated, you can email to the people in charge and tell them
what is wrong and what you think will improve. There are some documentation which is left
there so that we can read and understand history where it came from and some may still use
old version of cassandra.



  On Wed, Jul 23, 2014 at 7:49 PM, Jack Krupansky <jack@basetechnology.com> wrote:

    And the simplest and easiest thing to do is simply email this list when you see something
wrong or missing in the DataStax Cassandra doc, or for anything that is not adequately anywhere.
I work with the doc people there, so I can make sure they see corrections and improvements.
And simply sharing knowledge on this list is always a big step forward.

    -- Jack Krupansky

    From: spawgi@gmail.com 
    Sent: Wednesday, July 23, 2014 4:25 AM
    To: user@cassandra.apache.org 
    Subject: Re: Why is the cassandra documentation such poor quality?

    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