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