incubator-cassandra-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Denny Abraham <dennysabra...@gmail.com>
Subject Re: configuration file comments on wiki
Date Fri, 13 Nov 2009 23:50:22 GMT
Can this be added to the file itself and then be parsed along with the javadoc?

On Fri, Nov 13, 2009 at 2:54 PM, Jonathan Mischo <jmischo@quagility.com> wrote:
> 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
>>>>
>>>>
>>>
>>>
>
>

Mime
View raw message