cassandra-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Jon Haddad (JIRA)" <j...@apache.org>
Subject [jira] [Created] (CASSANDRA-8700) shut off the wiki
Date Wed, 28 Jan 2015 22:09:34 GMT
Jon Haddad created CASSANDRA-8700:
-------------------------------------

             Summary: shut off the wiki
                 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)

Mime
View raw message