cassandra-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jake Luciani <jak...@gmail.com>
Subject Re: Why is the cassandra documentation such poor quality?
Date Wed, 23 Jul 2014 15:41:30 GMT
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 <woolfel@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 <woolfel@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 <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.
>>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>
>>>>>
>>>>
>>>
>>
>


-- 
http://twitter.com/tjake

Mime
View raw message