+1 to asciidoc. My guess would be that more people are familiar with markdown, but asciidoc definitely has more to offer and is easy enough to use if you are familiar with markdown.
On Fri, Apr 24, 2020 at 11:24 AM Jon Haddad <j...@jonhaddad.com> wrote: > 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 > > > -- - John
