I'd like to get the docs out of Sphinx. I hate it. The syntax is crap and almost nobody knows it.
I'm fine with markdown (it makes it easy for most people) and have a personal preference for asciidoc, since it makes it easier to generate PDFs and is a bit richer / better for documentation. I'd go with markdown if it means more contributions though. I'd love to see the site maintained with Hugo. It's a really nice tool, I used it to build the reaper website [1] and the docs [2]. Source example for documentation here [3]. I won't have time for the conversion anytime soon, but if someone's willing to take it on I think it would really help with both writing and reviewing docs. [1] http://cassandra-reaper.io [2] http://cassandra-reaper.io/docs/ [3] https://github.com/thelastpickle/cassandra-reaper/blob/master/src/docs/content/docs/development.md On Fri, Apr 24, 2020 at 8:11 AM Joshua McKenzie <jmcken...@apache.org> wrote: > All, > > A few of us have the opportunity to offer a large portion of documentation > to the apache foundation and specifically the Apache Cassandra project as > well as dedicate a good portion of time to maintaining this going forward. > For those of you familiar, this is the DataStax sponsored / authored > Cassandra documentation people often refer to in the community. Links can > be found here > <https://docs.datastax.com/en/landing_page/doc/landing_page/cassandra.html > >. > > I've spoken with some of the doc writers and there's going to be > significant work involved to go from the doc writing system these are > authored in to Sphinx, or some other doc authoring system if we as a > project decide to switch things. I know Jon Haddad has some opinions here > and I think that'd be a great conversation to have on this thread for those > interested. A couple of people in the near future are going to have the > opportunity to continue working on these docs full-time in the in-tree > docs, so maintenance going forward should represent little disruption to > the project's workings day-to-day. > > Looking for feedback on: > > 1. > > Are there any questions or concerns about this donation? > 2. > > Any thoughts on documentation system to use long-term, since a donation > of this size would be a reasonable time to consider switching to > something > more preferable (not advocating for the system these current docs are > in to > be clear - poking Haddad to speak up since he has a strong PoV here ;) ) > 3. > > What are next steps? > > > I'm genuinely excited about this; here's to hoping everyone else is too! > > > ~Josh >
