cassandra-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Sylvain Lebresne (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
Date Fri, 24 Jun 2016 16:43:17 GMT

    [ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15348556#comment-15348556
] 

Sylvain Lebresne commented on CASSANDRA-8700:
---------------------------------------------

Friday update: the [branch|https://github.com/pcmanus/cassandra/commits/doc_in_tree] has all
the parts that has been submitted so far. I also (mostly) finished migrating the CQL doc (even
though there is still some parts that I plan to improve) and I reorganized the doc slightly.
Typically, having the whole CQL doc in the same file (being it source file or html output)
was really unwieldy, and that was kind of true of the other top-level topic, so I've split
things up a bit. The result can be (temporarily) seen [here|http://www.lebresne.net/~mcmanus/cassandra-doc-test/html/tools/index.html].

One thing I do want to point out again is that the current doc is for trunk. In a perfect
world, we'd have the same doc but adapted to earlier versions, but the main difference is
going to be the CQL doc, and trying to "rebuild" the CQL doc for earlier versions from the
migrated version is going to be really painful and time consuming and I'm not volunteering.
Besides, we can keep the link to the existing CQL doc for those old versions. So basically
I'm suggesting that we start publishing our new doc with 3.8, and from that point on, update
it only for tick-tock releases.

> 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 and Website
>            Reporter: Jon Haddad
>            Assignee: Sylvain Lebresne
>            Priority: Blocker
>             Fix For: 3.8
>
>         Attachments: TombstonesAndGcGrace.md, bloom_filters.md, compression.md, contributing.zip,
getting_started.zip, hardware.md
>
>
> 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