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