I do worry Markdown might not be a great choice. It's definitively most well know by a large margin, and that's a good, but it's also a bit limited (even with common extensions). It's perfect for comments, README or even somewhat informal docs, but we're talking the fairly large (and meant to grow) user facing documentation of a large and somewhat complex software, and a bit more flexibility is of definite use imo. I truly worry Markdown will effectively yield a lesser experience for user of the doc.
By how much, I'm not sure, but insofar that the documentation is read order of magnitudes more (and by order of magnitudes more people) than written, I'm not a fan of shrugging this off too quickly. Regarding asciidoc, it looks most likely capable enough, and I have no technical objection to its use on principle. But I'm also unconvinced it's a significantly better choice than restructuredText (currently used). Both syntax are different enough from Markdown that there is a bit of muscle memory to retrain, but both are also easy enough in general (it's all human readable markup) that it doesn't feel like a huge deal either. And while it's hard to get perfect data on this, a simple Google trends search ( https://trends.google.fr/trends/explore?date=today%205-y&q=markdown,asciidoc,restructuredText ) suggests that while asciidoc is a tad more popular (than rst), neither are ubiquitous enough for me to imagine that it'd make a meaningful difference. I'm really not against asciidoc, but also keep in mind the current doc has had some amount of setup: it's somewhat integrated to the website (though I'll admit it's debatable whether that's important to preserve or not), automatic syntax highlighting for CQL is already setup, etc. Switching to asciidoc is not "no work". Are we sufficiently certain it is worth it? Tl;dr, my current position is: 1. I'm rather cold on using markdown. I would insist on making a good case this won't meaningfully degrade the output quality before jumping ship. 2. I see the ROI of switching to asciidoc as rather small (the investment is non null, and the return not that clear to me, though I obviously may be missing some of the advantages of asciidoc over reStructuredText and will, as always, happily re-evaluate on new information). It won't oppose it if someone makes the work (and it's not botched), but I think the effort would be better spent elsewhere. -- Sylvain On Thu, Apr 30, 2020 at 5:02 AM John Sanda <john.sa...@gmail.com> wrote: > +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 >
