This is a great post… and really does a great job of summarizing the problems I have with the cassandra documentation.
I realize that Datastax is trying to step in and fix the problem.. but there are now a lot of parties involved (JIRA tickets, blog posts, datastax doc, apache doc, etc) … it's all over the place. Some coordination is needed. My suggestions would be: - take the apache wiki and documentation offline or put it in legacy… it's NOT helping Cassandra or Datastax new users when people stumble on old documentation giving them bad advice for commands that no longer exist. - take the datastax documentation and perhaps have Apache link to it or have Datastax contribute the documentation to Apache. It's not helping Datastax when their potential customers look at Cassandra and see poor and inconsistent documentation. - take some of the blog posts / JIRA tickets, and document the outcome somewhere. We can't have documentation hidden. - make sure Google returns the right documentation for queries. - make sure to include the version in the documentation on which version of cassandra it applies to… - consider using the MySQL documentation as an example. They've done a GREAT job maintaining their documentation over the years. IMO. … I think part of the problem is that the cassandra community has a lot of people who already know the ins and outs… so they don't see how difficult the problem is from a new user perspective. I have a lot of experience in distribute systems, understand the space well, but I just can't find documentation on how cassandra does things from a high level perspective. My plan is to just use the source code for reference. Not everyone has that option though… Kevin On Wed, Jul 23, 2014 at 5:29 AM, Nicholas Okunew <naoku...@gmail.com> wrote: > 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. > > -- Founder/CEO Spinn3r.com Location: *San Francisco, CA* blog: http://burtonator.wordpress.com … or check out my Google+ profile <https://plus.google.com/102718274791889610666/posts> <http://spinn3r.com>
