Mailing-List: contact cassandra-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: cassandra-dev@incubator.apache.org
Received-SPF: pass (nike.apache.org: domain of dennysabraham@gmail.com
 designates 209.85.218.210 as permitted sender)
DomainKey-Signature: a=rsa-sha1; c=nofws;
        d=gmail.com; s=gamma;
        h=mime-version:in-reply-to:references:date:message-id:subject:from:to
         :content-type:content-transfer-encoding;
        b=snYVHddgXQxPLkUy69Ev88TZLroOUoTJTFchycNd1ArB9kbDN6/mQ5QwkREGj7NEZp
         Uo/ALQUtPI6ixhpFYtbbGExHMsldsH73ksbMkjiMexgl6bBHtqdRQFHU8pwgQT2Ff+pC
         tqPQGGFGVPefZzDjkL3/YGT9cIsr2nZCPRCA4=
MIME-Version: 1.0
In-Reply-To: <1D958566-5AE8-4194-A709-D5ADE887BA4F@quagility.com>
References: <e06563880911130759k5a2b1daald9396b33a9b96d4@mail.gmail.com>
	 <4AFD89BB.5000209@gmail.com>
	 <ff027e5c0911131012w63c77810r76982f1045c5fcf2@mail.gmail.com>
	 <1D958566-5AE8-4194-A709-D5ADE887BA4F@quagility.com>
Date: Fri, 13 Nov 2009 17:50:22 -0600
Message-ID: <f38abbfa0911131550x42795e84r5396f14f9eaceb0c@mail.gmail.com>
Subject: Re: configuration file comments on wiki
From: Denny Abraham <dennysabraham@gmail.com>
To: cassandra-dev@incubator.apache.org
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable

Can this be added to the file itself and then be parsed along with the java=
doc?

On Fri, Nov 13, 2009 at 2:54 PM, Jonathan Mischo <jmischo@quagility.com> wr=
ote:
> 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. =A0Cassandra doesn't have a documentation project goin=
g
> 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. =A0If 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 go=
ing
> to continue to be fairly ad-hoc for a while. =A0As 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. =A0This 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 crea=
te
>>> 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. =A0I'd rather move that into the
>>>> config file itself though rather than have it get out of date when we
>>>> update things. =A0(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
>>>>
>>>>
>>>
>>>
>
>