As I mentioned, I really have nothing against asciidoc. In fact, I think it's great.
Let's just say that I think rst/sphinx is also pretty capable, and that I consider your characterization of the syntax difference (one "awful", the other "a dream") a tad over-the-top. I do agree on the point on documentation though, the asciidoc one is better (not that I find the rst one completely inadequate either), and I reckon it's a good argument. So to be clear, if someone makes the change to asciidoc and it's not botched, I won't personally stand in the way. I'll note however that asking we analyze the pros and cons of a change should not be seen as suspicious. And we should imo strive to justify any change with objective arguments. One's experience certainly increases the believability of one's arguments, but it doesn't dispense from presenting arguments in the first place. And I wish the substance of your previous email wasn't: I know, you don't, and the project don't have time to wait on you learning, so just trust me. > 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. Not really true of at least the CQL section. It makes somewhat extensive use of the 'productionlist::' feature. Which gives us decent formatting of the CQL grammar elements "for free", automatic cross-referencing within said grammar and easy cross-referencing to said grammar from the rest of the text. I think that's kind of nice? I could be wrong, but getting the same even with asciidoc is going to be much more manual, and definitively would with markdown. We also use 'note::' and 'warning::' boxes in a few places, and those are also nice to have imo, and I don't think mardown would give us that easily. We also define a jira "extlinks" (so that anywhere in the doc, ":jira:`42`" is replaced by a proper link named CASSANDRA-42 and pointing to that ticket) and it's used in a few places. Fwiw, it's this kind of things (and any future similar use we may want) I had in mind when discussing markdown being limited, and we can debate their importance, but we do use them. But maybe those don't qualify as "really" using advanced stuffs. How would I know, I'm the guy that needs to learn, you're the expert. -- Sylvain On Thu, Apr 30, 2020 at 4:11 PM Jon Haddad <j...@jonhaddad.com> wrote: > 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 > > > > > >
