Mailing-List: contact cassandra-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: cassandra-dev@incubator.apache.org
Received-SPF: pass (athena.apache.org: domain of jmischo@quagility.com
 designates 216.154.210.211 as permitted sender)
Message-Id: <1D958566-5AE8-4194-A709-D5ADE887BA4F@quagility.com>
From: Jonathan Mischo <jmischo@quagility.com>
To: cassandra-dev@incubator.apache.org
In-Reply-To: <ff027e5c0911131012w63c77810r76982f1045c5fcf2@mail.gmail.com>
Content-Type: text/plain; charset=US-ASCII; format=flowed; delsp=yes
Content-Transfer-Encoding: 7bit
Mime-Version: 1.0 (Apple Message framework v936)
Subject: Re: configuration file comments on wiki
Date: Fri, 13 Nov 2009 14:54:46 -0600
References: <e06563880911130759k5a2b1daald9396b33a9b96d4@mail.gmail.com>
  <4AFD89BB.5000209@gmail.com>
 <ff027e5c0911131012w63c77810r76982f1045c5fcf2@mail.gmail.com>

Typically you have an example configuration file that has information  
on the most common options, but doesn't have every single possible  
configuration option in it, and then official documentation that has  
deeper discussion of each and examples.  Cassandra doesn't have a  
documentation project going currently, so the problem, as Jonathan  
mentioned, is that it's very easy for the documentation and the  
example config to get out of sync very quickly.

As Cassandra matures, our documentation is going to have to become a  
lot more stable and robust.  If the project had corporate sponsorship,  
I'd suggest hiring a documentarian (I've done this before for  
projects...it's actually kind of fun), but we don't have sponsorship  
or money, so it's going to continue to be fairly ad-hoc for a while.   
As such, I'd suggest that we pick one place to document and stick to it.

The only alternative I see would be for one person to volunteer to  
watch all config file changes and update the wiki in a timely manner.   
This can't simply be a "Oh, I'll do that for 0.5" thing, it needs to  
be an ongoing thing (not eternally, but a long-term commitment would  
be ideal if you're going to take this on).

We are definitely approaching a point where we need an official  
documentarian, at least as the person who handles the structure and  
standards of documentation, even if they don't have the time/resources  
to write a lot of the docs (and, in fact, this is where the whole  
community usually jumps in).

On Nov 13, 2009, at 12:12 PM, kevin wrote:

> it will be great to have it in just one place. if it is in two  
> places it is
> going to be hard to figure out which is latest and correct.
>
>
> On Fri, Nov 13, 2009 at 8:30 AM, TuxRacer69 <tuxracer69@gmail.com>  
> wrote:
>
>> Hi Jonathan,
>>
>> That's me. I understand that it can be painful to update.
>>
>> However I would say that a project of the size and popularity of  
>> Cassandra
>> deserves a dedicated configuration documentation. Also the Wiki  
>> format
>> allows you to make links to other pages which obviously becomes
>> non-clickable when translated to XML. It allows you to add pictures  
>> too
>> which I plan to do to link the config parameters to an architecture
>> documentation (wiki).
>>
>> As per porting the wiki to 0.5, I volunteer to update the page (or  
>> create a
>> 0.5 version of that page);
>>
>> what do you think?
>>
>> Alex
>>
>>
>>
>> Jonathan Ellis wrote:
>>
>>> Hi,
>>>
>>> Someone has been industriously improving the documentation of the
>>> config file settings on the wiki.  I'd rather move that into the
>>> config file itself though rather than have it get out of date when  
>>> we
>>> update things.  (E.g. moving from 0.4 to 0.5 RSN.)
>>>
>>> I'd appreciate it if you could submit a patch for the xml instead.
>>>
>>> -Jonathan
>>>
>>>
>>
>>