[jira] [Comment Edited] (CASSANDRA-8700) replace the wiki with docs in the git repo

["Jon Haddad (JIRA)" <ji...@apache.org>]

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

Jon Haddad edited comment on CASSANDRA-8700 at 1/28/15 11:37 PM:
-----------------------------------------------------------------

{quote}
It still puts the onus on the comitters' shoulders, though.
{quote}

Your point is valid, having the committers bottlenecked on docs might be problematic.  I know you guys have a lot on your plate already, it may be asking too much for docs merges as well.  On the other hand, considering though the frequency of edits (even if the current rate was tripled) it would only be a handful a week.  If it actually managed got out of control I feel like someone would have to step up as the docs maintainer.  

{quote}
I feel you there, but that's an infra problem. If it worked in a sane amount of time would you feel differently? We could ping infra to see what's up here.
{quote}

I think that would be a massive step forward, and probably the correct initial one.  If that's possible, I think the pragmatic approach would be to:

a) improve the wiki performance (couple seconds to save is fine)
b) reevaluate wiki usage in a few months to see if it's improved usage.  


was (Author: rustyrazorblade):
{quote}
It still puts the onus on the comitters' shoulders, though.
{quote}

Your point is valid, having the committers bottlenecked on docs might be problematic.  I know you guys have a lot on your plate already, it may be asking too much for docs merges as well.  Considering though the frequency of edits (even if the current rate was tripled) it would only be a handful a week.  If it actually got out of control I feel like someone would have to step up as the docs maintainer.

{quote}
I feel you there, but that's an infra problem. If it worked in a sane amount of time would you feel differently? We could ping infra to see what's up here.
{quote}

I think that would be a massive step forward, and probably the correct initial one.  If that's possible, I think the pragmatic approach would be to:

a) improve the wiki performance (couple seconds to save is fine)
b) reevaluate wiki usage in a few months to see if it's improved usage.  

> 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)