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