incubator-cassandra-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From TuxRacer69 <tuxrace...@gmail.com>
Subject Re: configuration file comments on wiki
Date Sat, 14 Nov 2009 10:13:22 GMT
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).
>


Mime
View raw message