[
https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14296000#comment-14296000
]
Jon Haddad commented on CASSANDRA-8700:
---------------------------------------
{quote}
The problem with this is, only committers can contribute.
{quote}
Well, not really. Anyone can submit a JIRA w/ a doc update. It's not
excluding anyone.
{quote}
I can put you in the contributors group
{quote}
I'm actually in there already. It's such a nightmare to save a change (5
minutes last time I tried) that I just never do it.
{quote}
Really though, some of it is, some of it isn't
{quote}
You're able to find plenty of things that are true, and just as many that are
out dated. One of the benefits of putting the docs in git is that it removes
ambiguity that currently exists in the wiki. For instance - how would you
document counters? There's caveats, changes to implementation, etc, that need
to be told to the user trying to work with Cassandra. If that was versioned
along with the codebase, it becomes substantially easier to manage. Again, I
reference cqlengine, where we did both a wiki & docs in repo and it worked
great.
> replace the wiki with docs in the git repo
> ------------------------------------------
>
> Key: CASSANDRA-8700
> URL: https://issues.apache.org/jira/browse/CASSANDRA-8700
> Project: Cassandra
> Issue Type: Improvement
> Components: Documentation & website
> Reporter: Jon Haddad
> Priority: Minor
>
> The wiki as it stands is pretty terrible. It takes several minutes to apply
> a single update, and as a result, it's almost never updated. The information
> there has very little context as to what version it applies to. Most people
> I've talked to that try to use the information they find there find it is
> more confusing than helpful.
> I'd like to propose that instead of using the wiki, the doc directory in the
> cassandra repo be used for docs (already used for CQL3 spec) in a format that
> can be built to a variety of output formats like HTML / epub / etc. I won't
> start the bikeshedding on which markup format is preferable - but there are
> several options that can work perfectly fine. I've personally use sphinx w/
> restructured text, and markdown. Both can build easily and as an added bonus
> be pushed to readthedocs (or something similar) automatically. For an
> example, see cqlengine's documentation, which I think is already
> significantly better than the wiki:
> http://cqlengine.readthedocs.org/en/latest/
> In addition to being overall easier to maintain, putting the documentation in
> the git repo adds context, since it evolves with the versions of Cassandra.
> If the wiki were kept even remotely up to date, I wouldn't bother with this,
> but not having at least some basic documentation in the repo, or anywhere
> associated with the project, is frustrating.
> For reference, the last 3 updates were:
> 1/15/15 - updating committers list
> 1/08/15 - updating contributers and how to contribute
> 12/16/14 - added a link to CQL docs from wiki frontpage (by me)
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
