[prev in list] [next in list] [prev in thread] [next in thread] 

List:       cassandra-dev
Subject:    Re: configuration file comments on wiki
From:       TuxRacer69 <tuxracer69 () gmail ! com>
Date:       2009-11-14 10:13:22
Message-ID: 4AFE82C2.4030105 () gmail ! com
[Download RAW message or body]

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

[prev in list] [next in list] [prev in thread] [next in thread]