[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15351581#comment-15351581 ] Sylvain Lebresne commented on CASSANDRA-8700: - As we wanted to have the new doc (even if incomplete) for 3.8 and we're about to freeze 3.8, I committed the branch. I'm sure everyone will agree this is better than what we have. Not that this is just so that some doc is included with the 3.8 artifacts, but I'll only push the doc online next week (with the release of 3.8) and we can still add/improve things till then. So I suggest keeping this ticket open until next week, and if someone has updates to the doc he want to suggest, he can just put it here and I'll include it directly. Once 3.8 is out, I'll close this ticket and we can start using new ticket for new contributions normally. > 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15351203#comment-15351203 ] Jonathan Ellis commented on CASSANDRA-8700: --- bq. 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. +1 > 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15340216#comment-15340216 ] T Jake Luciani commented on CASSANDRA-8700: --- Monitoring/Metrics PR https://github.com/pcmanus/cassandra/pull/60 > 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15340003#comment-15340003 ] Joshua McKenzie commented on CASSANDRA-8700: Change data capture PR: https://github.com/pcmanus/cassandra/pull/59 > 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15336860#comment-15336860 ] Sylvain Lebresne commented on CASSANDRA-8700: - bq. Let me know what you think. I'll look at it next week cause it's getting late, but I have no doubt it beats the hell out of doing this manually. That's great. Anyway, outside of that pull request (and the next one on sstable and memtables) the branch includes everything I got so far, including the section on compaction by Marcus and Jeff that Marcus sent me by email. I'm myself still working on the CQL doc. Overall, I think it's safe to say that we'll have something decent to publish by the end of next week (we might still have a handful of missing sections by then, but they should be few enough that we can put it online). > 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15336835#comment-15336835 ] Tyler Hobbs commented on CASSANDRA-8700: Memtable and SSTable architecture: https://github.com/pcmanus/cassandra/pull/58 > 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[
https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15336742#comment-15336742
]
Tyler Hobbs commented on CASSANDRA-8700:
Pull request to automatically convert cassandra.yaml into rst:
https://github.com/pcmanus/cassandra/pull/57
This works pretty well overall. There are a few minor downsides:
* I couldn't figure out a good way to handle complex options (lists and dicts)
without hard coding the option names in the script. I considered using a yaml
parser to detect these, but that would add a dependency and wouldn't work for
commented-out complex options. Fortunately, it's a pretty small list, and
should rarely change. If it does change without us updating the script, it
won't break anything, but the option body will end up in the next section.
* Some of the existing comments needed to be formatted slightly differently to
look good in rst.
* A couple of comments and default values don't make as much sense in the rst
version. For example, {{allocate_tokens_for_keyspace}} has a default value of
{{KEYSPACE}}, which is really more of a placeholder. In the rst version, this
is shown as the default value, so it's a little weird. The number of quirks
like this is fairly small, though, and they're not terrible.
Let me know what you think.
> 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15336734#comment-15336734 ] T Jake Luciani commented on CASSANDRA-8700: --- bq. cherry-picked because I like my branches like my complexities: linear Oh good. I was going to ask that you keep the commits so attribution/blame works. > 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15336400#comment-15336400 ] Sam Tunnicliffe commented on CASSANDRA-8700: Pull request for security: https://github.com/pcmanus/cassandra/pull/56 > 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[
https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15334573#comment-15334573
]
Tyler Hobbs commented on CASSANDRA-8700:
bq. On the cqlsh doc though, I wonder if it's a good idea to include the
description of the command line options, and even of the special commands?
Feels like it we'll easily forgot to update it and it doesn't seem to add a lot
of value over getting the help from cqlsh directly.
I think the main advantage is that this documentation will show up in search
results. This is particularly useful if you don't know what you're looking
for, or you don't know if it's a commandline thing or a special command. I
also considered including docs for {{cqlshrc}} here for the same reason, but
those are technically already online and searchable (although not nicely
formatted).
However, it would be nice to generate the docs directly from the code, as you
mention. Sphinx works well with python, so this is probably reasonable to do.
I'll look into it.
> 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[
https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15333615#comment-15333615
]
Sylvain Lebresne commented on CASSANDRA-8700:
-
I included the pull requests made so far on [my
branch|https://github.com/pcmanus/cassandra/commits/doc_in_tree] (cherry-picked
because I like my branches like my complexities: linear). Note that I'm the
middle of fixing the CQL doc so that's why it looks bad currently (I'm taking
the time to add missing parts and reorganize things a bit so it's taking a bit
of time).
On the cqlsh doc though, I wonder if it's a good idea to include the
description of the command line options, and even of the special commands?
Feels like it we'll easily forgot to update it and it doesn't seem to add a lot
of value over getting the help from cqlsh directly. Maybe we could just point
to how to get said help (just mentioning that you should use {{cqlsh -h}} for
command line options and that there is a HELP command within cqlsh)? Or maybe
we can have all that generated from cqlsh code directly so things stay in sync
automatically?
> 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15332742#comment-15332742 ] Tyler Hobbs commented on CASSANDRA-8700: Pull request for replication and tunable consistency levels: https://github.com/pcmanus/cassandra/pull/55 > 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15332407#comment-15332407 ] Tyler Hobbs commented on CASSANDRA-8700: Pull requests for cqlsh docs: https://github.com/pcmanus/cassandra/pull/54 > 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15332356#comment-15332356 ] Sylvain Lebresne commented on CASSANDRA-8700: - bq. I suggest not putting the generated HTML in git, but rather have it be a build artifact like a jar would be. That's exactly what it does currently, and I agree with the general sentiment, but in practice our web site is managed through SVN (through some kind of pubsub managed by the ASF) so the html will have to get there at some point (but we push to the website rarely and without concurrency so I don't think "it'll turn into a mess" in practice). And my mention that I'd rather have this done with git rather than SVN is completely orthogonal to the documentation problem, I was just rambling, let's forget about it here. > 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15332106#comment-15332106 ] Jon Haddad commented on CASSANDRA-8700: --- I suggest not putting the generated HTML in git, but rather have it be a build artifact like a jar would be. If you do any sort of image generation through plugins like nwdiag (for network diagrams) it'll turn into a mess. Doesn't the ASF provide some space for this sort of thing? > 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 > 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15330581#comment-15330581 ] Paulo Motta commented on CASSANDRA-8700: Created [PR|https://github.com/pcmanus/cassandra/pull/53] with snitch and range movements section drafts. > 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 > 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[
https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15329585#comment-15329585
]
Sylvain Lebresne commented on CASSANDRA-8700:
-
So, progress update: I've pushed a WIP branch
[here|https://github.com/pcmanus/cassandra/commits/doc_in_tree] with a first
version of the doc. It contains the outline from the google doc document
Jonathan mentioned above with the few sections attached here (by [~Stefania],
[~jjirsa] and [~rspitzer]) filled. I've also put the CQL doc but the conversion
from textile didn't went too well so it's pretty broken right now and I'm going
to work on fixing that next.
As said above, it uses sphinx (and the sphinx_rtd_theme; if you have neither,
it's a {{pip install sphinx sphinx_rtd_theme}} away) and I've added a
{{gen-doc}} ant target to build the html (but it actually just delegates to the
{{Makefile}} that sphinx provides, which can be used to build other formats
like pdf, epub, ...). There is a new {{README.md}} file in {{doc/}} that
explains all that.
Currently, the static html is put in a {{doc/build/}} directory, and once we're
ready to put that online, we'll probably have to copy that manually since the
website is not in git. On that topic, would be nice to see if we can get that
to change, moving the site in git so we can automate publishing a bit more
easily.
Another point worth mentioning is that the branch is against trunk and that I
used the CQL doc from there. So if we want to commit to earlier branch, we'll
theoretically have to change the CQL doc used (and as said above, it's a bit
painful to migrate). Alternatively, we could commit in trunk only and say that
for earlier versions, user should check the CQL doc changelog to figure out if
a given CQL feature is available in their version.
Anyway, I guess the most important thing missing is content: most of it is
currently TODO. So let's try to continue focusing on filling the blanks. You
are, btw, welcome to create pull-request against my branch above for that (but
I'm also still fine with just attaching particular chapters here as as been
done so far).
And for those that are curious how it currently looks like and can't be
bothered to compile it locally, I've pushed the current version temporarily
[here|http://www.lebresne.net/~mcmanus/cassandra-doc-test/html/index.html]
(again, the CQL part is broken, working on it).
> 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
> 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15329528#comment-15329528 ] Stefania commented on CASSANDRA-8700: - Added "How to get in touch" to installation.md and fixed the link in the first paragraph of "Prerequisites", no changes to drivers_list.md. See diff [here|https://github.com/stef1927/cassandra/commit/6f86ad99e8fafc37d3b4627e321b18e808bd0e1d#diff-4faf6ca666a60bc9a44a6495a6f028a0]. > 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 > 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15329505#comment-15329505 ] Sylvain Lebresne commented on CASSANDRA-8700: - [~Stefania] How different are the installation.md and drivers_list.md from that new zip from the one you previously attached? Did you just put them in a zip or did you updated them? > 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 > 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15329184#comment-15329184 ] Stefania commented on CASSANDRA-8700: - Added [^getting_started.zip], which contains installation.md and drivers_list.md, along with a new file: contact_us.md. Also added [^contributing.zip], which contains documentation on how to contribute, build and test. This may need moving to Confluence later on. > 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 > 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15327521#comment-15327521 ] Sylvain Lebresne commented on CASSANDRA-8700: - I had a look at what could be good options here. I'm sure I've missed some but some reasonable (as in, good without being too complex) options seems to be: * [textile|http://redcloth.org/textile]: I mention it _only_ because it's currently used for the CQL doc, but having written a fair amount of said doc, I hate it and am against continuing to use it (the top reason for my hatred being that new lines in the input are mirorred in the output which is just extremely annoying). * [sphinx|http://www.sphinx-doc.org/]: Was mentioned by a few people already and it is a great option. It's reasonably simple while being fairly complete and maintained. The main downside seems to be that reStructuredText is not always as pleasant to work with than say markdown (probably debatable but internet seems to generally agree on that). That said, reStructuredText is not that bad either and it's arguably more capable than markdown for some things. Sphinx also has a bunch of extension, and while I'm not sure we'll need that much, some might come in handy someday. * [MkDocs|http://www.mkdocs.org/]: A nice option in that it's simple but still produce decently looking docs (with navigation and search), and it uses markdown, which has the advantage of being more well known. It is however arguably less flexible than sphinx: in particular it doesn't seem to be able to easily produce pdfs, which would be nice to have. * [asciidoc|http://asciidoc.org/]: Haven't looked at it _that_ close but it's definitively capable (it's use by hbase for [their book|https://hbase.apache.org/book.html] in particular, and it doesn't look bad) but sphinx seems to have strictly more advantages. * [mdBook|http://azerupi.github.io/mdBook/]: uses mardown so not too disimilar to MkDocs, but slightly less capable (doesn't probide search for instance). Also made for the rust book so requires to install rust which is inconvenient (since we have no dependency on rust currently). * There is also a bunch of tools to convert from one markup languages to html, amongst which the more general is probably [pandoc|http://pandoc.org/], but those are probably a bit too crude. Anyway, I'm happy to check other options and debate which is best but it seems that sphinx (which has had some vote already) is a pretty good choice and so I've started setting it up (I'll try to commit a first WIP version of the outline plus the sections attached above tomorrow). If we decide that we prefer another option in the coming days, that's fine, I'll just convert the files (which is pretty simple with pandoc, so if you've already written something in markdown, feel free to attach it that way, I'll convert). > 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 > Attachments: TombstonesAndGcGrace.md, bloom_filters.md, > compression.md, drivers_list.md, hardware.md, installation.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 -
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15326059#comment-15326059 ] Mahdi Mohammadi commented on CASSANDRA-8700: In this way, it will be much easier for non-committers to update documentation. > 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 > Attachments: drivers_list.md, installation.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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15325980#comment-15325980 ] Jonathan Ellis commented on CASSANDRA-8700: --- Sphinx is also my own preference, but I'm fine with starting with markdown until we can have a proper discussion of the options. > 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 > Attachments: drivers_list.md, installation.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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15322091#comment-15322091 ] Giampaolo commented on CASSANDRA-8700: -- I "vote" for Sphinx + reStructuredText too. Recently I did some documentation with it and was a smooth experience > 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 > Attachments: drivers_list.md, installation.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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15321161#comment-15321161 ] Sylvain Lebresne commented on CASSANDRA-8700: - Btw, when you've writing a chapter you wanted to write, please just attach the markdown file to this ticket for now. I'll also deal with massing it all in a coherent form, review and get committed later. > 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15321147#comment-15321147 ] Sylvain Lebresne commented on CASSANDRA-8700: - bq. Let's standardize on Markdown for now (Sylvain's choice after being disenchanted with Textile for the CQL doc); we can convert to other formats easily enough later if necessary. To be clear, I'm in the process of evaluating different options (of which there is tons of) and I'll update this ticket (probably next week) with findings, after which we can decide what we want to use. But we shouldn't block writing the content on that, so let's just do markdown for now and if we decide for a different format later, I'll just convert everything we have. > 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15321144#comment-15321144 ] Jon Haddad commented on CASSANDRA-8700: --- I'd like to suggest we use Sphinx and Restructured Text instead of vanilla Markdown. Sphinx provides a lot of really useful plugins out of the box (like table of contents) plus various themes, can export a variety of formats (PDF / HTML / epub) and there's nice third party plugins like network & block diagrams. > 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15321131#comment-15321131 ] Jonathan Ellis commented on CASSANDRA-8700: --- I've mirrored the outline above to a gdoc so we can coordinate work more easily. Just put your name down by a section you plan to tackle, like (Alex), then post a patch. Let's standardize on Markdown for now (Sylvain's choice after being disenchanted with Textile for the CQL doc); we can convert to other formats easily enough later if necessary. I'm slightly leery of posting a world-editable gdoc here where it can get crawled, but I've posted it to IRC. Ping me or Sylvain if you need the link. Or you can just post a comment here saying what section you want to work on. > 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15320612#comment-15320612 ] Nate McCall commented on CASSANDRA-8700: bq. Truly, I see 2 big advantages to having the doc in-tree: I want to add what I consider to be the most important advantage: doing this will lower the barrier to entry for community participation and potentially allow us to expand the contributor base. We have some of the best operators around contributing to the community on the ML, in IRC, etc. and this will provide an avenue for those who can't/don't want to write Java to participate. > 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[
https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15319336#comment-15319336 ] Jonathan Ellis commented on CASSANDRA-8700: --- Here is my outline: Index.html - Suggest flat directory structure (index.html, cql.html, gettingstarted.html, etc) - Update generate-cql-html in build.xml to build everything Getting Started - Installation (Can follow Wiki reasonably closely) - Cqlsh Data Modeling / CQL - Existing doc is good, just including for completeness Operating Cassandra (can follow wiki but update as appropriate, e.g. we can assume vnodes by default now) - ReplicationStrategy - Adding and removing nodes - Repair - Compaction + Size Tiered + Leveled + TimeWindow - Leave out soon-to-be-deprecated DateTiered - Tombstones and gcgs - Backups - Monitoring - Nodetool (Can we autogenerate this from Nodetool’s help?) Troubleshooting - GCInspector and SystemLogger + tpstats FAQ - Limitations > 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 >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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanelfocusedCommentId=14339091#comment-14339091 ] Jonathan Ellis commented on CASSANDRA-8700: --- can they import the moin wiki? do we want to? 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanelfocusedCommentId=14339083#comment-14339083 ] T Jake Luciani commented on CASSANDRA-8700: --- I've gotten access to manage our old confluence wiki from CASSANDRA-145 https://cwiki.apache.org/confluence/display/CSDR/Index I'll add the core team to have edit rights on the wiki. 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanelfocusedCommentId=14339097#comment-14339097 ] Jon Haddad commented on CASSANDRA-8700: --- I think it would be worth it to still discuss a more deliberate structure, to at least have a framework in place, rather than an organic one. 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanelfocusedCommentId=14339139#comment-14339139 ] Jonathan Ellis commented on CASSANDRA-8700: --- Sure, but I'm throwing that project back at you. :) bq. Jon, can you put together an outline of what you have in mind for minimum viable docs? 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanelfocusedCommentId=14337533#comment-14337533 ] Jonathan Ellis commented on CASSANDRA-8700: --- My biggest problem with the wiki is that it's so ridiculously slow that everyone has given up trying to update it. Perhaps migrating to confluence would fix that. (/cc [~tjake]) But I agree that it would be nice, in theory, to have docs appropriate to the right C* version. Jon, can you put together an outline of what you have in mind for minimum viable docs? 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanelfocusedCommentId=14297268#comment-14297268 ] Jon Haddad commented on CASSANDRA-8700: --- If the question is in regard to my original issue - the generated docs could go anywhere, including ASF infrastructure. I put readthedocs because it's straightforward but it's not necessary. 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanelfocusedCommentId=14297224#comment-14297224 ] Jonathan Ellis commented on CASSANDRA-8700: --- I don't think ASF would be down with relying on 3rd party infrastructure. Or is that not what you're suggesting? 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanelfocusedCommentId=14297222#comment-14297222 ] Russ Hatch commented on CASSANDRA-8700: --- Someone else mentioned this in #cassandra-dev room already, but we could use the github wiki system on the mirror. If I understand correctly, GH creates a separate repo for wiki content so I don't think there's any risk of the mirror getting out of sync with the apache git repo. For updates people could fork the wiki repo and open pull requests, so this would not leave community updaters out in the cold. 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanelfocusedCommentId=14297232#comment-14297232 ] Russ Hatch commented on CASSANDRA-8700: --- bq. Or is that not what you're suggesting? I guess that's what I was suggesting, but not if it would make waves. 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[
https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanelfocusedCommentId=14296060#comment-14296060
]
Jon Haddad commented on CASSANDRA-8700:
---
{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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanelfocusedCommentId=14296038#comment-14296038 ] Brandon Williams commented on CASSANDRA-8700: - bq. Well, not really. Anyone can submit a JIRA w/ a doc update. It still puts the onus on the comitters' shoulders, though. bq. It's such a nightmare to save a change (5 minutes last time I tried) that I just never do it. 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. 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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[
https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanelfocusedCommentId=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)
[jira] [Commented] (CASSANDRA-8700) replace the wiki with docs in the git repo
[ https://issues.apache.org/jira/browse/CASSANDRA-8700?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanelfocusedCommentId=14295971#comment-14295971 ] Brandon Williams commented on CASSANDRA-8700: - bq. instead of using the wiki, the doc directory in the cassandra repo be used for docs The problem with this is, only committers can contribute. If you look at the [contributors group|https://wiki.apache.org/cassandra/ContributorsGroup] on the wiki, it's a pretty long list and regularly people request contributor access (I know because I do the bulk of the adding.) bq. If the wiki were kept even remotely up to date I can put you in the contributors group :) Really though, some of it is, some of it isn't. http://wiki.apache.org/cassandra/ArchitectureGossip for instance is quite accurate. 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)
