I've got a bit of experience here using all three systems we're discussing here.
* rst & sphinx: I've handled most of the doc reviews for Cassandra, written quite a bit of them as well, and I authored most of the documentation for cqlengine [1] * markdown: all over the place, let's be honest, it's ubiquitous. Within the community I built the Reaper website [2], the docs are all markdown and work fine. Source [3] if you're interested. * asciidoctor: tlp-stress [3] (src [4]) and tlp-cluster [5] (src [6]) were *extremely* nice to use. My favorite part here was the Gradle plugin to generate documentation making it a breeze to integrate into my build system. You're right about markdown being a little limited, but we're not really using anything advanced in sphinx. We write basic text with links and a menu. I don't know if that will ever change, but given my experience with Hugo + markdown on the reaper website, I'd say it's perfectly fine for writing technical documentation. I also write a *lot* of documentation for clients at TLP, which was all technical writing. I would regularly deliver 30-60 page cluster analysis documents written in markdown with tables, CQL, and code. I absolutely love asciidoc. Moving from markdown was really, really easy. In fact, most markdown will render properly in asciidoctor. The documentation is excellent and it's designed for writing. I even have a (private) repo where I'm writing a cookbook, something that requires just as much attention to detail and flexibility as technical writing. Take a look at the quick reference [7] to see some examples (this is my go to document if I forget the syntax). The quick ref here is *so good* that it only takes a second if you can't remember what you need. rst & sphinx have poor documentation (imo) in comparison. I find the syntax to be difficult to get right at times. Tables [8], for instance, are particularly awful, whereas in markdown or asciidoc they're a dream in comparison [9]. I recently wrote the production recommendations page [10] for C* and was *struggling* with the tables. It's like trying to write code with a stick in the ground after using IDEA. I'm not sure how you're calculating ROI, or why. There are people willing to do the work, and nobody is asking you to. I'm willing to lead the effort and work with the technical writers at datastax to make this happen. The investment cost is irrelevant to the project because time is donated, and unless you're someone's manager it shouldn't matter how much time they invest. Even if you are, that's a private matter not relevant to the list. If the writers are willing to help migrate documentation, I'm willing to shepherd the process, and I absolutely love that they're willing to help in this area. >From a technical angle, I ask that you trust my experience and judgement using all three tools extensively over a long period of time (3 years minimum, 10 years of rst). I have written thousands of pages of technical documentation in my life and I understand the pros and cons of all three systems and have weighed the costs of each of them for the last several months. Otherwise, you're asking for the rest of the project to wait while you become an expert in the remaining tooling. I doubt you have the time (or interest) in doing that. I know, without question, asciidoctor will give us the richest documentation with a very quick learning curve, so it's my personal preference. I'm 100% sure someone someone that is already familiar with markdown will find it easy to move to asciidoc since they're so similar in structure and the syntax is mostly compatible. I understand you don't want to see the project docs fall into a state of disrepair and as the person maintaining most of the docs today, I agree! I remember you did the initial work because I created the JIRA to do so. We've both invested a lot of time in the docs, so hopefully you trust that I don't take this lightly and wouldn't want to make the change without expecting to see a big payoff in the end. Jon [1] https://cqlengine.readthedocs.io/en/latest/ [2] http://cassandra-reaper.io [3] http://thelastpickle.com/tlp-stress/ [4] https://github.com/thelastpickle/tlp-stress/blob/master/manual/MANUAL.adoc [5] https://github.com/thelastpickle/tlp-cluster/blob/master/manual/src/index.adoc [6] http://github.com/thelastpickle/tlp-cluster [7] https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/ [8] https://docutils.sourceforge.io/docs/user/rst/quickref.html#tables [9] https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#tables [10] https://issues.apache.org/jira/browse/CASSANDRA-8700 On Thu, Apr 30, 2020 at 6:05 AM Sylvain Lebresne <lebre...@gmail.com> wrote: > 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 > > >
