configuration file comments on wiki

[Jonathan Ellis <jb...@gmail.com>]

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

Re: configuration file comments on wiki

[TuxRacer69 <tu...@gmail.com>]

Eric Evans wrote:
> Actually, I think it would be great to have it in both places, the
> problem stems from each being updated independently (and yes, one of
> them will almost certainly suffer from lack of updates). 
>
> I don't suppose something like Doxygen could be made to work with xml
I believe it would be difficult to include links to images and cross 
links to the wiki.
Also updating the wiki automatically could be tricky as information 
could come from two sources: SVN (developers) and the wiki itself (wiki 
users). You would get into complex merge issues.
The amount of time to spend to create such a system seems high (in 
comparison to the time I spent to create a wiki page and the time I 
would spend to include the version dependant information).

Re: configuration file comments on wiki

[Eric Evans <ee...@rackspace.com>]

Dropping -dev (and hoping it sticks)...

On Fri, 2009-11-13 at 10:12 -0800, 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.

Actually, I think it would be great to have it in both places, the
problem stems from each being updated independently (and yes, one of
them will almost certainly suffer from lack of updates). 

I don't suppose something like Doxygen could be made to work with xml?

> On Fri, Nov 13, 2009 at 8:30 AM, TuxRacer69 <tu...@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.

-- 
Eric Evans
eevans@rackspace.com

Re: configuration file comments on wiki

[TuxRacer69 <tu...@gmail.com>]

Jonathan Mischo 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).

Is there an easy way to watch all Jiras having a documentation impact?
At the company I work for we have a tickbox called "Has a Documentation 
Impact" for each Jira.
I'd be happy to update the wiki.


>
> 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).
>

Re: configuration file comments on wiki

[Bill de hOra <bi...@dehora.net>]

 > 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


OSS projects can do first rate documentation if the will is there 
(Django and Spring come to mind).  So why not start a doc area in the 
trunk? Sphinx would do the trick nicely.

Bill

Jonathan Mischo 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 <tu...@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
>>>>
>>>>
>>>
>>>
> 

Re: configuration file comments on wiki

[Denny Abraham <de...@gmail.com>]

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 <jm...@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 <tu...@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
>>>>
>>>>
>>>
>>>
>
>

Re: configuration file comments on wiki

[Jonathan Mischo <jm...@quagility.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 <tu...@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
>>>
>>>
>>
>>

Re: configuration file comments on wiki

[kevin <ke...@gmail.com>]

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 <tu...@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
>>
>>
>
>

Re: configuration file comments on wiki

[kevin <ke...@gmail.com>]

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 <tu...@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
>>
>>
>
>

Re: configuration file comments on wiki

[TuxRacer69 <tu...@gmail.com>]

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
>   

Re: configuration file comments on wiki

[TuxRacer69 <tu...@gmail.com>]

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
>