cassandra-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Benedict Elliott Smith <belliottsm...@datastax.com>
Subject Re: Why is the cassandra documentation such poor quality?
Date Wed, 23 Jul 2014 12:22:46 GMT
All requests I've seen in the past year to edit the wiki (admittedly only
2-3) have been answered promptly with editing privileges. Personally I
don't have a major preference either way for policy - there are positives
and negatives to each approach - but, like I said, raise it on the dev list
and see if anybody else does.

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




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

>
> I've submitted requests to edit the wiki in the past and nothing ever got
> done.
>
> Having been an apache committer and contributor over the years, I can
> totally understand that people are busy. I also understand that "most"
> developer find writing docs tedious.
>
> I'd rather not harass the committers about wiki edits, since I didn't like
> it when it happened to me in the past. That's why many apache projects keep
> their wiki's open. Honestly, as much as I find writing docs challenging and
> tedious, it's critical and important. For my other open source projects, I
> force myself to write docs.
>
> my point is, the wiki should be open and the barrier should be removed.
> Having to "beg/ask" to edit the wiki feels like a slap in the face to me,
> but maybe I'm alone in this. Then again, I've heard the same sentiment from
> other people about cassandra's wiki. The thing is, they just chalk it up to
> "cassandra committers don't give a crap about docs". I do my best to defend
> the committers and point out some are volunteers, but it does give the
> public a negative impression. I know the committers care about docs, but
> they don't always have time to do it.
>
> I know that given a choice between coding or writing docs, 90% of the time
> I'll choose coding. What I've decided instead is to document stuff on one
> of my blogs.  If someone gets lucky, maybe google will return the result. I
> keep asking myself "what's the point of closing a wiki?"
>
>
>
> On Wed, Jul 23, 2014 at 7:40 AM, Benedict Elliott Smith <
> belliottsmith@datastax.com> wrote:
>
>> It only takes a moment to ask to be added as a wiki contributor; if you
>> email the dev list or ask on irc, somebody with privileges will ordinarily
>> add you within a day. It may be a psychological barrier, but it isn't
>> really a practical one. Still, if you feel the policy is incorrect, raise
>> this on the dev list also.
>>
>>
>> On Wed, Jul 23, 2014 at 1:33 PM, Peter Lin <woolfel@gmail.com> wrote:
>>
>>>
>>> I've tried to contribute docs to Cassandra wiki in the past, but there's
>>> an obstacle.
>>>
>>> currently wiki.apache.org/cassandra is locked down, so only commiters
>>> can edit it. I really wish that wasn't the case, since it wastes time. the
>>> commiters are busy writing code. Having to email a commiter and ask them to
>>> update it feels silly to me and kind of goes against openness. Back when I
>>> was active with JMeter, we decided to leave it open so that anyone can edit
>>> the docs.
>>>
>>> I can't be the only one that wants to help make the docs better, but get
>>> frustrated with the wiki being closed.
>>>
>>>
>>>
>>> On Wed, Jul 23, 2014 at 4:25 AM, <spawgi@gmail.com> wrote:
>>>
>>>> I would like to help out with the documentation of C*. How do I start?
>>>>
>>>>
>>>> On Wed, Jul 23, 2014 at 12:46 PM, Robert Stupp <snazy@snazy.de> wrote:
>>>>
>>>>> Just a note:
>>>>> If you have suggestions how to improve documentation on the datastax
>>>>> website, write them an email to docs@datastax.com. They appreciate
>>>>> proposals :)
>>>>>
>>>>> Am 23.07.2014 um 09:10 schrieb Mark Reddy <mark.reddy@boxever.com>:
>>>>>
>>>>> Hi Kevin,
>>>>>
>>>>> The difference here is that the Apache Cassandra site is maintained by
>>>>> the community whereas the DataStax site is maintained by paid employees
>>>>> with a vested interest in producing documentation.
>>>>>
>>>>> With DataStax having some comprehensive docs, I guess the desire for
>>>>> people to maintain the Apache site has dwindled. However, if you are
>>>>> interested in contributing to it and bringing it back up to standard
you
>>>>> can, thus is the freedom of open source.
>>>>>
>>>>>
>>>>> Mark
>>>>>
>>>>>
>>>>> On Wed, Jul 23, 2014 at 2:54 AM, Kevin Burton <burton@spinn3r.com>
>>>>> wrote:
>>>>>
>>>>>> This document:
>>>>>>
>>>>>> https://wiki.apache.org/cassandra/Operations
>>>>>>
>>>>>> … for example.  Is extremely out dated… does NOT reflect 2.x
releases
>>>>>> certainly.  Mentions commands that are long since removed/deprecated.
>>>>>>
>>>>>> Instead of giving bad documentation, maybe remove this and mark it
as
>>>>>> obsolete.
>>>>>>
>>>>>> The datastax documentation… is … acceptable I guess.  My main
>>>>>> criticism there is that a lot of it it is in their blog.
>>>>>>
>>>>>> Kevin
>>>>>>
>>>>>> --
>>>>>>
>>>>>> Founder/CEO Spinn3r.com <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.
>>>>
>>>
>>>
>>
>

Mime
View raw message