You are viewing a plain text version of this content. The canonical link for it is here.
Posted to user@cassandra.apache.org by Kevin Burton <bu...@spinn3r.com> on 2014/07/23 03:54:48 UTC
Why is the cassandra documentation such poor quality?
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
<https://plus.google.com/102718274791889610666/posts>
<http://spinn3r.com>
Re: Why is the cassandra documentation such poor quality?
Posted by Kevin Burton <bu...@spinn3r.com>.
On Wed, Jul 23, 2014 at 4:55 AM, Jason Wee <pe...@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.
>
>
You clearly didn't look at my post history.
Further, you CAN'T just spend time searching google and reading, because
the documentation is all over the place, inaccurate, etc.
--
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>
Re: Why is the cassandra documentation such poor quality?
Posted by Robert Coli <rc...@eventbrite.com>.
On Wed, Jul 23, 2014 at 11:44 AM, Kevin Burton <bu...@spinn3r.com> wrote:
> 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 belief as to the reason why you are unable to find design documents
which explicate the design principles behind Apache Cassandra is that
neither exist.
I continue to be a firm believer that a documented set of design principles
we all agree are "Cassandric" would be very helpful in cases where we need
to evaluate whether proposed patches are "Cassandric" enough to merge.
My plan is to just use the source code for reference. Not everyone has
> that option though…
>
This, and people who have done the same and combined it with following JIRA
for regressions/bugfixes, are the path to the most accurate understanding
of how any given release of Cassandra works.
=Rob
Re: Why is the cassandra documentation such poor quality?
Posted by Kevin Burton <bu...@spinn3r.com>.
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 <na...@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>
Re: Why is the cassandra documentation such poor quality?
Posted by Redmumba <re...@gmail.com>.
A lot of the information about the compaction strategies would be
incredibly useful in the docs as well:
http://www.datastax.com/dev/blog/leveled-compaction-in-apache-cassandra
On Thu, Jul 24, 2014 at 9:45 AM, Peter Lin <wo...@gmail.com> wrote:
> for example, this old blog entry from way back in 2012
>
> http://www.datastax.com/dev/blog/cql3-for-cassandra-experts
>
>
> On Thu, Jul 24, 2014 at 12:07 PM, Tyler Hobbs <ty...@datastax.com> wrote:
>
>>
>> On Thu, Jul 24, 2014 at 3:55 AM, Nicholas Okunew <na...@gmail.com>
>> wrote:
>>
>>> most of the important stuff being in blog format
>>
>>
>> Which blog posts are you referring to? We could definitely have the docs
>> team integrate some of the blog post topics into the normal docs and keep
>> them updated for new C* versions.
>>
>>
>> --
>> Tyler Hobbs
>> DataStax <http://datastax.com/>
>>
>
>
Re: Why is the cassandra documentation such poor quality?
Posted by Peter Lin <wo...@gmail.com>.
for example, this old blog entry from way back in 2012
http://www.datastax.com/dev/blog/cql3-for-cassandra-experts
On Thu, Jul 24, 2014 at 12:07 PM, Tyler Hobbs <ty...@datastax.com> wrote:
>
> On Thu, Jul 24, 2014 at 3:55 AM, Nicholas Okunew <na...@gmail.com>
> wrote:
>
>> most of the important stuff being in blog format
>
>
> Which blog posts are you referring to? We could definitely have the docs
> team integrate some of the blog post topics into the normal docs and keep
> them updated for new C* versions.
>
>
> --
> Tyler Hobbs
> DataStax <http://datastax.com/>
>
Re: Why is the cassandra documentation such poor quality?
Posted by Peter Lin <wo...@gmail.com>.
for starters all of the blog entries related to CQL3, like the change in
terminology and compact storage.
the last time I looked at the datastax documentation on CQL3, it wasn't
nearly as detailed as the blog entries by jonathan ellis and sylvain.
On Thu, Jul 24, 2014 at 12:07 PM, Tyler Hobbs <ty...@datastax.com> wrote:
>
> On Thu, Jul 24, 2014 at 3:55 AM, Nicholas Okunew <na...@gmail.com>
> wrote:
>
>> most of the important stuff being in blog format
>
>
> Which blog posts are you referring to? We could definitely have the docs
> team integrate some of the blog post topics into the normal docs and keep
> them updated for new C* versions.
>
>
> --
> Tyler Hobbs
> DataStax <http://datastax.com/>
>
Re: Why is the cassandra documentation such poor quality?
Posted by Peter Lin <wo...@gmail.com>.
there's quite a few blog entries on Datastax blog that really should be
included in the docs
On Thu, Jul 24, 2014 at 5:32 PM, Hao Cheng <br...@critica.io> wrote:
> I second this, especially since the version association for blog posts is
> often vague. This makes looking at historical blog posts quite annoying
> because it's difficult to tell if some of the specific advice has changed
> since.
> On Jul 24, 2014 2:23 PM, "Jack Krupansky" <ja...@basetechnology.com> wrote:
>
>> Blog posts are great for highlighting and focusing the community on
>> new features, changes, and techniques, but any knowledge content in them
>> definitely needs to be in the docs as well.
>>
>> -- Jack Krupansky
>>
>> *From:* Tyler Hobbs <ty...@datastax.com>
>> *Sent:* Thursday, July 24, 2014 12:07 PM
>> *To:* user@cassandra.apache.org
>> *Subject:* Re: Why is the cassandra documentation such poor quality?
>>
>>
>> On Thu, Jul 24, 2014 at 3:55 AM, Nicholas Okunew <na...@gmail.com>
>> wrote:
>>
>>> most of the important stuff being in blog format
>>
>>
>> Which blog posts are you referring to? We could definitely have the docs
>> team integrate some of the blog post topics into the normal docs and keep
>> them updated for new C* versions.
>>
>>
>> --
>> Tyler Hobbs
>> DataStax <http://datastax.com/>
>>
>
Re: Why is the cassandra documentation such poor quality?
Posted by Hao Cheng <br...@critica.io>.
I second this, especially since the version association for blog posts is
often vague. This makes looking at historical blog posts quite annoying
because it's difficult to tell if some of the specific advice has changed
since.
On Jul 24, 2014 2:23 PM, "Jack Krupansky" <ja...@basetechnology.com> wrote:
> Blog posts are great for highlighting and focusing the community on new
> features, changes, and techniques, but any knowledge content in them
> definitely needs to be in the docs as well.
>
> -- Jack Krupansky
>
> *From:* Tyler Hobbs <ty...@datastax.com>
> *Sent:* Thursday, July 24, 2014 12:07 PM
> *To:* user@cassandra.apache.org
> *Subject:* Re: Why is the cassandra documentation such poor quality?
>
>
> On Thu, Jul 24, 2014 at 3:55 AM, Nicholas Okunew <na...@gmail.com>
> wrote:
>
>> most of the important stuff being in blog format
>
>
> Which blog posts are you referring to? We could definitely have the docs
> team integrate some of the blog post topics into the normal docs and keep
> them updated for new C* versions.
>
>
> --
> Tyler Hobbs
> DataStax <http://datastax.com/>
>
Re: Why is the cassandra documentation such poor quality?
Posted by Jack Krupansky <ja...@basetechnology.com>.
Blog posts are great for highlighting and focusing the community on new features, changes, and techniques, but any knowledge content in them definitely needs to be in the docs as well.
-- Jack Krupansky
From: Tyler Hobbs
Sent: Thursday, July 24, 2014 12:07 PM
To: user@cassandra.apache.org
Subject: Re: Why is the cassandra documentation such poor quality?
On Thu, Jul 24, 2014 at 3:55 AM, Nicholas Okunew <na...@gmail.com> wrote:
most of the important stuff being in blog format
Which blog posts are you referring to? We could definitely have the docs team integrate some of the blog post topics into the normal docs and keep them updated for new C* versions.
--
Tyler Hobbs
DataStax
Re: Why is the cassandra documentation such poor quality?
Posted by Tyler Hobbs <ty...@datastax.com>.
On Thu, Jul 24, 2014 at 3:55 AM, Nicholas Okunew <na...@gmail.com> wrote:
> most of the important stuff being in blog format
Which blog posts are you referring to? We could definitely have the docs
team integrate some of the blog post topics into the normal docs and keep
them updated for new C* versions.
--
Tyler Hobbs
DataStax <http://datastax.com/>
Re: Why is the cassandra documentation such poor quality?
Posted by Nicholas Okunew <na...@gmail.com>.
No - it took me a little while to see what is going on with datastax, I
wasn't interested in datastax/DSE. I was interested in Cassandra.
I see the value of datastax supporting Cassandra, I think it's a lot
further along than it would have been without their support. But they've
also vacuumed up all the knowledge and talent and 'sell' it. They have a
good business model and I don't have anything against them, but I do think
that a lot of the knowledge and detail is locked up in their docs. I don't
think its particularly well managed - in particular most of the important
stuff being in blog format - you need to interpret the timeframes and a lot
more to really figure out what current best practice is and feature sets
available to you are. Otherwise you're digging through documentation of
enterprise software trying to figure out which bits apply to you.
A few examples:
There has been a bit of chatter about counter columns not being right,
maybe unstable, but they'll be much better in 2.1 flavours. However they're
50% of the reason I went with C* at the time, and everything I was reading
was sending me in that direction. The information I was reading was only
correct at a point in time.
The other 50% was dynamic columns, but there was (and still is I think) a
lot of confusion around CQL3 and thrift style wide rows. All of the
confusion is around the nonclamenture and the point in time the docs you
happen to be reading were written. Something as integral as partition and
cluster keys requires interpretation to understand - that doesn't seem
right.
Anyway, I will check out the training, its been a while since I've been
learning - mostly doing lately.
On Thursday, July 24, 2014, Jack Krupansky <ja...@basetechnology.com> wrote:
> 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 <pe...@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 <ja...@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 <sn...@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 <ma...@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 <bu...@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 <http://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/>
>>>>>
>>>>>
>>>>
>>>>
>>>>
>>>>
>>>
>>>
>>>
>>> --
>>> http://spawgi.wordpress.com
>>> We can do it and do it better.
>>>
>>
>>
>
>
Re: Why is the cassandra documentation such poor quality?
Posted by Jack Krupansky <ja...@basetechnology.com>.
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 <pe...@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 <ja...@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 <sn...@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 <ma...@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 <bu...@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.
Re: Why is the cassandra documentation such poor quality?
Posted by Nicholas Okunew <na...@gmail.com>.
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 <pe...@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 <ja...@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 <sn...@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 <ma...@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 <bu...@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 <http://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/>
>>>>
>>>>
>>>
>>>
>>>
>>>
>>
>>
>>
>> --
>> http://spawgi.wordpress.com
>> We can do it and do it better.
>>
>
>
Re: Why is the cassandra documentation such poor quality?
Posted by Jason Wee <pe...@gmail.com>.
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 <ja...@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 <sn...@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 <ma...@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 <bu...@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 <http://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/>
>>>
>>>
>>
>>
>>
>>
>
>
>
> --
> http://spawgi.wordpress.com
> We can do it and do it better.
>
Re: Why is the cassandra documentation such poor quality?
Posted by Jack Krupansky <ja...@basetechnology.com>.
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 <sn...@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 <ma...@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 <bu...@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.
Re: Why is the cassandra documentation such poorquality?
Posted by Dave Brosius <db...@mebigfatguy.com>.
We had a massive spam problem before we locked down the wiki, so
unfortunately that was the choice we had to make. But as stated we can
add you to the contributers list.
What is your Wiki user name?
On 2014-07-23 07:33, Peter Lin wrote:
> I've tried to contribute docs to Cassandra wiki in the past, but there's an obstacle.
>
> currently wiki.apache.org/cassandra [1] 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, <sp...@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 <sn...@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 <ma...@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 <bu...@spinn3r.com> wrote:
>
> This document:
>
> https://wiki.apache.org/cassandra/Operations [2]
>
> … 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 [3]
> Location: SAN FRANCISCO, CA
> blog: http://burtonator.wordpress.com [4]
> … or check out my Google+ profile [5]
> [3]
--
http://spawgi.wordpress.com [6]
We can do it and do it better.
Links:
------
[1] http://wiki.apache.org/cassandra
[2] https://wiki.apache.org/cassandra/Operations
[3] http://spinn3r.com/
[4] http://burtonator.wordpress.com/
[5] https://plus.google.com/102718274791889610666/posts
[6] http://spawgi.wordpress.com
Re: Why is the cassandra documentation such poor quality?
Posted by Peter Lin <wo...@gmail.com>.
it supports CQL, but it's through thrift. I don't currently support native
protocol, since that was evolving rapidly last year when I made the port.
I state clearly on nectar-client wiki on google code that it supports CQL3
via thrift. I've pretty much given up on cassandra wiki. Using my blog to
share knowledge about Cassandra is quicker, easier and immediate. Downside
is it doesn't come up on google search, so it's really just for myself and
my friends.
On Wed, Jul 23, 2014 at 8:52 AM, Jack Krupansky <ja...@basetechnology.com>
wrote:
> 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 <wo...@gmail.com>
> *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 <wo...@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 <wo...@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, <sp...@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 <sn...@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 <ma...@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 <bu...@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 <http://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/>
>>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>> --
>>>>>> http://spawgi.wordpress.com
>>>>>> We can do it and do it better.
>>>>>>
>>>>>
>>>>>
>>>>
>>>>
>>>
>>>
>>
>>
>
>
Re: Why is the cassandra documentation such poor quality?
Posted by Jack Krupansky <ja...@basetechnology.com>.
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 <be...@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 <wo...@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 <be...@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 <wo...@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, <sp...@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 <sn...@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 <ma...@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 <bu...@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.
Re: Why is the cassandra documentation such poor quality?
Posted by Jake Luciani <ja...@gmail.com>.
I'll note that historically the wiki used to be open to all and due massive
amounts of spam it was put on lockdown by the ASF.
If there is a better platform the community feels would make it simpler to
provide community based documentation then we should consider it.
The ASF also has confluence wiki which might be simpler for users to
contribute to? (at least they have captchas)
-Jake
On Wed, Jul 23, 2014 at 9:20 AM, Peter Lin <wo...@gmail.com> wrote:
> @benedict - you're right that I've haven't requested permission to edit.
> You're also right that I've given up on getting edit permission to
> cassandra wiki. I've been struggling and struggled with "how" to manage
> open source projects, so I totally get it. Managing projects is a thankless
> job most of the time. Pleasing everyone is totally impossible. Apache isn't
> alone in this. I've submitted stuff to google's open source projects in the
> past and had it go into a black hole. We all struggle with managing open
> source projects.
>
> I am committed to contributing Cassandra community, but just not through
> the wiki. There's lots of different ways to contribute. The jira tickets
> I've submitted have gotten good responses generally. It does take several
> days depending on how busy the committers are, but that's normal for all
> projects.
>
>
>
> On Wed, Jul 23, 2014 at 9:00 AM, Benedict Elliott Smith <
> belliottsmith@datastax.com> wrote:
>
>> Requesting a change is very different to requesting permission to edit
>> (which, I note, still hasn't been made); we do our best to promote
>> community engagement, so granting a privilege request has a different
>> mental category to a random edit request, which is much more likely to be
>> forgotten by any particular committer in the process of attending to their
>> more pressing work.
>>
>> The relationship between committers and the community is debated at
>> length in all projects, often by vocal individuals such as yourselves who
>> are unhappy in some way with how the project is being run. However it is
>> very hard to please everyone - most of the time we can't even please all
>> the committers, and that is a much smaller and more homogenous group.
>>
>>
>>
>>
>>
>> On Wed, Jul 23, 2014 at 2:30 PM, Peter Lin <wo...@gmail.com> wrote:
>>
>>>
>>> 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 <wo...@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 <wo...@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, <sp...@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 <sn...@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 <bu...@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 <http://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/>
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>> --
>>>>>>>> http://spawgi.wordpress.com
>>>>>>>> We can do it and do it better.
>>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>
>>>>>
>>>>
>>>
>>
>
--
http://twitter.com/tjake
Re: Why is the cassandra documentation such poor quality?
Posted by Jeremy Jongsma <je...@barchart.com>.
My experience is similar to Nicholas'. Basic usage was easy to get a handle
on, but the advanced tuning/tweaking info is scattered EVERYWHERE around
the web, mostly on personal blogs. It feels like it took way too long to
become confident enough in my understanding of Cassandra that I trust our
deployment configuration in production.
Without this mailing list I would still be on the fence.
On Wed, Jul 23, 2014 at 8:20 AM, Peter Lin <wo...@gmail.com> wrote:
> @benedict - you're right that I've haven't requested permission to edit.
> You're also right that I've given up on getting edit permission to
> cassandra wiki. I've been struggling and struggled with "how" to manage
> open source projects, so I totally get it. Managing projects is a thankless
> job most of the time. Pleasing everyone is totally impossible. Apache isn't
> alone in this. I've submitted stuff to google's open source projects in the
> past and had it go into a black hole. We all struggle with managing open
> source projects.
>
> I am committed to contributing Cassandra community, but just not through
> the wiki. There's lots of different ways to contribute. The jira tickets
> I've submitted have gotten good responses generally. It does take several
> days depending on how busy the committers are, but that's normal for all
> projects.
>
>
>
> On Wed, Jul 23, 2014 at 9:00 AM, Benedict Elliott Smith <
> belliottsmith@datastax.com> wrote:
>
>> Requesting a change is very different to requesting permission to edit
>> (which, I note, still hasn't been made); we do our best to promote
>> community engagement, so granting a privilege request has a different
>> mental category to a random edit request, which is much more likely to be
>> forgotten by any particular committer in the process of attending to their
>> more pressing work.
>>
>> The relationship between committers and the community is debated at
>> length in all projects, often by vocal individuals such as yourselves who
>> are unhappy in some way with how the project is being run. However it is
>> very hard to please everyone - most of the time we can't even please all
>> the committers, and that is a much smaller and more homogenous group.
>>
>>
>>
>>
>>
>> On Wed, Jul 23, 2014 at 2:30 PM, Peter Lin <wo...@gmail.com> wrote:
>>
>>>
>>> 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 <wo...@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 <wo...@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, <sp...@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 <sn...@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 <bu...@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 <http://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/>
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>> --
>>>>>>>> http://spawgi.wordpress.com
>>>>>>>> We can do it and do it better.
>>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>
>>>>>
>>>>
>>>
>>
>
Re: Why is the cassandra documentation such poor quality?
Posted by Peter Lin <wo...@gmail.com>.
@benedict - you're right that I've haven't requested permission to edit.
You're also right that I've given up on getting edit permission to
cassandra wiki. I've been struggling and struggled with "how" to manage
open source projects, so I totally get it. Managing projects is a thankless
job most of the time. Pleasing everyone is totally impossible. Apache isn't
alone in this. I've submitted stuff to google's open source projects in the
past and had it go into a black hole. We all struggle with managing open
source projects.
I am committed to contributing Cassandra community, but just not through
the wiki. There's lots of different ways to contribute. The jira tickets
I've submitted have gotten good responses generally. It does take several
days depending on how busy the committers are, but that's normal for all
projects.
On Wed, Jul 23, 2014 at 9:00 AM, Benedict Elliott Smith <
belliottsmith@datastax.com> wrote:
> Requesting a change is very different to requesting permission to edit
> (which, I note, still hasn't been made); we do our best to promote
> community engagement, so granting a privilege request has a different
> mental category to a random edit request, which is much more likely to be
> forgotten by any particular committer in the process of attending to their
> more pressing work.
>
> The relationship between committers and the community is debated at length
> in all projects, often by vocal individuals such as yourselves who are
> unhappy in some way with how the project is being run. However it is very
> hard to please everyone - most of the time we can't even please all the
> committers, and that is a much smaller and more homogenous group.
>
>
>
>
>
> On Wed, Jul 23, 2014 at 2:30 PM, Peter Lin <wo...@gmail.com> wrote:
>
>>
>> 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 <wo...@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 <wo...@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, <sp...@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 <sn...@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 <ma...@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 <bu...@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 <http://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/>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> --
>>>>>>> http://spawgi.wordpress.com
>>>>>>> We can do it and do it better.
>>>>>>>
>>>>>>
>>>>>>
>>>>>
>>>>
>>>
>>
>
Re: Why is the cassandra documentation such poor quality?
Posted by Ben Hood <0x...@gmail.com>.
On Wed, Jul 23, 2014 at 1:30 PM, Peter Lin <wo...@gmail.com> wrote:
>
> 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.
>
TL;DR There is something wrong with Cassandra information sharing, but I am
partly to blame.
My experience has not been too dissimilar to Peter's. I've had raised JIRA
tickets that haven't been answered and requests to the wiki that haven't
been answered. But I do appreciate that everybody is busy and things do
slip through the cracks sometimes, as they do with things I'm responsible
for.
That said, I have received help from community via this mailing list, for
which I am grateful. For example, when I was trying to get an update to the
Apache wiki, Brady from DataStax helped me out with the Planet Cassandra
wiki.
In defence of the people trying to manage Cassandra, some of the
limitations are down to the structure of Apache projects. I don't want to
start an issue tracker flame war, but I feel that a lot of oversight has
gone missing in Apache's JIRA installation. Last week I raised a ticket
that was (incorrectly) marked as a duplicate, due to an oversight in the
affected version field. The reason for this is the unhelpful way the JIRA
page was rendered - I can completely empathize with the person who closed
it.
Because of things like this, I always think four times over before raising
a ticket in JIRA. This is also not the right approach either, and I am
partly to blame. Just this week, a member of the community took the time to
do the right thing when raising a issue and they also went to effort of
supplying a patch for the issue I had chosen not to put into JIRA.
So I think there is something wrong with the way the community is sharing
its common knowledge, but I don't have a better suggestion. How are you
going to get a bunch of disparate people together to write cohesive
documentation that is in sync with the current release?
Furthermore, As a maintainer of a CQL driver, I have little if any contact
with any contact with any of the other driver maintainers. They must be out
there, but I don't know of a forum for them. It might not be needed, but
sometimes I feel like it should. So I'm just as guilty as everybody else of
not creating this community.
Re: Why is the cassandra documentation such poor quality?
Posted by Benedict Elliott Smith <be...@datastax.com>.
Requesting a change is very different to requesting permission to edit
(which, I note, still hasn't been made); we do our best to promote
community engagement, so granting a privilege request has a different
mental category to a random edit request, which is much more likely to be
forgotten by any particular committer in the process of attending to their
more pressing work.
The relationship between committers and the community is debated at length
in all projects, often by vocal individuals such as yourselves who are
unhappy in some way with how the project is being run. However it is very
hard to please everyone - most of the time we can't even please all the
committers, and that is a much smaller and more homogenous group.
On Wed, Jul 23, 2014 at 2:30 PM, Peter Lin <wo...@gmail.com> wrote:
>
> 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 <wo...@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 <wo...@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, <sp...@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 <sn...@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 <ma...@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 <bu...@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 <http://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/>
>>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>
>>>>>>
>>>>>> --
>>>>>> http://spawgi.wordpress.com
>>>>>> We can do it and do it better.
>>>>>>
>>>>>
>>>>>
>>>>
>>>
>>
>
Re: Why is the cassandra documentation such poor quality?
Posted by Peter Lin <wo...@gmail.com>.
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 <wo...@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 <wo...@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, <sp...@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 <sn...@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 <ma...@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 <bu...@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 <http://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/>
>>>>>>>
>>>>>>>
>>>>>>
>>>>>>
>>>>>
>>>>>
>>>>> --
>>>>> http://spawgi.wordpress.com
>>>>> We can do it and do it better.
>>>>>
>>>>
>>>>
>>>
>>
>
Re: Why is the cassandra documentation such poor quality?
Posted by Benedict Elliott Smith <be...@datastax.com>.
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 <wo...@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 <wo...@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, <sp...@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 <sn...@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 <ma...@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 <bu...@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 <http://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/>
>>>>>>
>>>>>>
>>>>>
>>>>>
>>>>
>>>>
>>>> --
>>>> http://spawgi.wordpress.com
>>>> We can do it and do it better.
>>>>
>>>
>>>
>>
>
Re: Why is the cassandra documentation such poor quality?
Posted by Peter Lin <wo...@gmail.com>.
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 <wo...@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, <sp...@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 <sn...@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 <ma...@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 <bu...@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 <http://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/>
>>>>>
>>>>>
>>>>
>>>>
>>>
>>>
>>> --
>>> http://spawgi.wordpress.com
>>> We can do it and do it better.
>>>
>>
>>
>
Re: Why is the cassandra documentation such poor quality?
Posted by Benedict Elliott Smith <be...@datastax.com>.
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 <wo...@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, <sp...@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 <sn...@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 <ma...@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 <bu...@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 <http://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/>
>>>>
>>>>
>>>
>>>
>>
>>
>> --
>> http://spawgi.wordpress.com
>> We can do it and do it better.
>>
>
>
Re: Why is the cassandra documentation such poor quality?
Posted by Peter Lin <wo...@gmail.com>.
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, <sp...@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 <sn...@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 <ma...@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 <bu...@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 <http://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/>
>>>
>>>
>>
>>
>
>
> --
> http://spawgi.wordpress.com
> We can do it and do it better.
>
Re: Why is the cassandra documentation such poor quality?
Posted by sp...@gmail.com.
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 <sn...@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 <ma...@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 <bu...@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 <http://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/>
>>
>>
>
>
--
http://spawgi.wordpress.com
We can do it and do it better.
Re: Why is the cassandra documentation such poor quality?
Posted by Robert Stupp <sn...@snazy.de>.
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 <ma...@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 <bu...@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
>
>
>
Re: Why is the cassandra documentation such poor quality?
Posted by Mark Reddy <ma...@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 <bu...@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
> <https://plus.google.com/102718274791889610666/posts>
> <http://spinn3r.com>
>
>