[
https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15319498#comment-15319498
]
Sylvain Lebresne commented on CASSANDRA-8700:
---------------------------------------------
{quote}
I've gotten access to manage our old confluence wiki from CASSANDRA-145
https://cwiki.apache.org/confluence/display/CSDR/Index
{quote}
You'll have to tell me how your managed that. I naively though using the INFRA
jira would be a good way but apparently not:
https://issues.apache.org/jira/browse/INFRA-10942.
bq. having the committers bottlenecked on docs might be problematic.
I _strongly_ doubt this would happen and I kind of would love for that to
happen. We have had our CQL doc in tree for a while now, and that hasn't even
remotely be a problem. Besides, I haven't doc an extensive study of the
question, but I suspect the doc of most open source project is primarily
written by the main contributor of said project, which really kind of make
sense.
Truly, I see 2 big advantages to having the doc in-tree:
# this makes it easier for us to keep the doc up-to-date: if a ticket changes
something that impact documentation, including the change in the patch is a lot
easier that not forgetting to go update some wiki when the patch gets committed.
# this guarantees the documentation is somewhat reviewed. Imo, that's actually
important.
So, me very much in favor of having the doc in-tree, and I plan on taking some
time in next few days to setting something up.
> 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: 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)
