Good summation, yes. Let's just clear markdown off the table, it's not enough for what we need to do.
I spoke briefly with Paul and Lorina, and I think we're all OK with updating the rst docs for now, with a longer term plan to migrate everything to asciidoc. The priority should be improving what we have for 4.0. Once that's released we can mess with the doc & website system. There's a nice project that builds on top of asciidoctor called Antora [1] that's specifically built to create documentation websites like ours that might be a good fit for our needs, but we need to evaluate it with a POC to know for sure. [1] https://antora.org On Fri, May 15, 2020 at 7:29 AM Sylvain Lebresne <lebre...@gmail.com> wrote: > On Thu, May 14, 2020 at 10:08 PM Joshua McKenzie <jmcken...@apache.org> > wrote: > > > Where did we land on this? Sylvain, Jon, Paul - are you three working > > through differences of opinion in another forum, or has this discussion > > stalled? > > > > I don't feel there is much unresolved differences of opinions (but I could > be > wrong and feel free to correct me), though maybe it's worth summarizing > where > we are. > > The only 3 options that have been mentioned here have been: > 1. moving to markdown > 2. moving to asciidoc > 3. sticking to RST/sphinx > > Afaict: > - there seems to be relatively good consensus on the fact that markdown, > for > all its qualities, is too limiting for our purpose here. > - there also seem to be good consensus on the fact that asciidoc would work > fine (Jon is a bit proponent, and unless I misunderstood, all the > features > that Paul mentioned as important are supported by asciidoc). > - the only difference of POV is on whether asciidoc provides enough > benefits > over RST to justify migrating. But while I express personal doubt on > that, > this is just an opinion and, as I already said, I'm not going to be in > the > way of such migration if it is done (I just won't push for it either). > > Of course, maybe others have opinions, they haven't yet voiced, or other > options they want to propose. > > -- > Sylvain > > > > > > > If the latter, how do we unstall it? > > > > On Wed, May 6, 2020 at 3:37 PM Joshua McKenzie <jmcken...@apache.org> > > wrote: > > > > > Great point about it not being hierarchical Paul; that logic resonates > > > with me. > > > > > > On Wed, May 6, 2020 at 11:50 AM Paul Tepley <ptep...@datastax.com> > > wrote: > > > > > >> To address your comments, the point I was trying to make is that > > >> correctness, completeness, and usability are really not hierarchical. > > From > > >> a user's point of view not finding information is frustrating, > incorrect > > >> information is frustrating, and incomplete information is frustrating. > > >> Individual user's reaction to these frustrations will vary from taking > > it > > >> in stride to abandoning a product. > > >> > > >> Wrong in documentation isn't analogous to incorrect code. Incorrect > code > > >> breaks something, but there are levels of wrong in docs that can still > > >> provide enough information for users to accomplish tasks or to gain > > >> knowledge. Obviously we don't want any incorrect docs, but it's not > the > > >> same as incorrect coding. > > >> > > >> The thing that is really most important from a tech writer's > perspective > > >> is a system designed to produce documentation is much better than one > > that > > >> is not. For a complex product like Cassandra, the ability to reuse is > > >> paramount because it promotes writing solution-based documents and > > >> maintainability. Without which, productivity goes down, accuracy goes > > down, > > >> and usability goes down. > > >> > > >> On 2020/05/05 15:14:00, Joshua McKenzie <jmcken...@apache.org> wrote: > > >> > > > > >> > > usability and ease of consumption is just as important if not > more > > as > > >> > > correctness and coverage. > > >> > > > >> > I disagree pretty strongly with this. There is negative value in > > >> > documentation that's incorrect and inaccurate. Much like comments or > > >> code: > > >> > if it's wrong, I posit that nothing else matters. Honestly, if > > >> > documentation were wrong it'd probably be better if it were > impossible > > >> to > > >> > find. :) > > >> > > > >> > Without the ability to locate information you want, correctness and > > >> > > coverage are meaningless. > > >> > > > >> > This implies a binary situation which is, I believe, hyperbolic. I > > >> think it > > >> > would be more accurate to say "The most correct and thorough > > >> documentation > > >> > in the world can be completely hamstrung if it can't be navigated". > > >> > > > >> > All are important; we need correct, thorough, and easily navigable > and > > >> > usable documentation. But we also need a way to value different > > >> > documentation frameworks against one another or we're going to get > > >> > gridlocked in a vigorous airing of opinions where nobody changes > their > > >> PoV > > >> > and eventually whichever side is the most stubborn "wins", or the > > topic > > >> > just rots on the vine, neither of which are healthy. > > >> > > > >> > On Mon, May 4, 2020 at 7:20 PM Paul Tepley <ptep...@datastax.com> > > >> wrote: > > >> > > > >> > > The order Josh mentions seems correct, but usability and ease of > > >> > > consumption is just as important if not more as correctness and > > >> coverage. > > >> > > > > >> > > In technical writing, the key elements to usability and ease of > > >> > > consumption are findability and searchability. Findability means > > >> finding > > >> > > information for something you want to do without knowing what it > is > > >> > > beforehand. Searchability is finding information you know about > > using > > >> > > the terms that you know. The key to effective documentation is > that > > >> > > information is both findable and searchable in "terms that the > users > > >> know". > > >> > > A simple example is gossip. If you know nothing about Cassandra, > you > > >> > > probably understand that nodes talk to each other, which you might > > >> search > > >> > > for using "internode communication" or "network communication". > > >> > > > > >> > > Without the ability to locate information you want, correctness > and > > >> > > coverage are meaningless. > > >> > > > > >> > > Another principle that makes good documentation is that they are > > >> > > solution-based. Two examples are replacing a node and adding a > node. > > >> > > > > >> > > Another important feature of being able to produce accurate and > > >> complete > > >> > > docs is the ability to reuse information. Using the previous > > examples, > > >> > > replacing a node and adding a node, may have some of the same > steps. > > >> > > Reusing information is not saving time by writing only once, it's > > >> about > > >> > > making sure that when information is updated, it's updated > > everywhere > > >> it > > >> > > needs to be (especially in places you don't know about). Having a > > >> single > > >> > > source for reusing information is essential to making this happen. > > >> > > > > >> > > Also, related to reusing information, the ability to pull from a > > >> central > > >> > > location using includes/shortcodes/etc. can ease the testability > and > > >> > > findability of code examples used in documentation. Rather than > > >> scattering > > >> > > code throughout the docs, you can store the code snippets in their > > own > > >> > > repo. For instance, asciidoc has such a capability (amongst > others): > > >> > > > > >> > > [source,ruby] > > >> > > ---- > > >> > > include::example.rb[] > > >> > > ---- > > >> > > > > >> > > The last feature I want to mention that contributes to good > > >> documentation > > >> > > is semantic structure. The idea of semantic structure is similar > to > > >> > > object-oriented programming, where objects contain data. So > instead > > of > > >> > > manually defining all the attributes of the warning, you can just > > >> declare > > >> > > the warning and add the data. For example, suppose you want a > > warning > > >> that > > >> > > says "Don't do this, it will kill your system!" In a non-semantics > > >> > > authoring, such as Markdown (designed as format for writing for > the > > >> web), > > >> > > you'd have to define each element: > > >> > > > > >> > > **Warning** > > >> > > Don't do this, it will kill your system! > > >> > > > > >> > > The problem here is not so much having to define each element but > > >> that a > > >> > > different writer can do something different, such as vary the > > marking > > >> from > > >> > > ** to *, as there is no enforced structure: > > >> > > > > >> > > *Warning* > > >> > > Don't do this, it will kill your system! > > >> > > > > >> > > Although this is a very simple example, not being able to enforce > a > > >> > > standard can be confusing to the user because clues to using the > > >> > > documentation lack consistency and refinement. > > >> > > > > >> > > In semantics-based documentation, such in reStructuredText, you > can > > >> just > > >> > > write > > >> > > > > >> > > . warning:: Don't do this, it will kill your system! > > >> > > > > >> > > and every instance will be consistent. > > >> > > > > >> > > I realize that everyone wants something simple that they don't > have > > to > > >> > > learn, but doing so will: > > >> > > > > >> > > 1) Decrease the efficiency of writing docs, which reduces the > > >> likelihood > > >> > > of complete coverage. > > >> > > 2) Reduce correctness, because the writer does not necessarily > know > > >> > > everywhere information needs to be updated. > > >> > > 3) Diminish the usability and ease of consumption. For example, a > > >> lack of > > >> > > consistency reduces the ability of the user to quickly scan a > > >> document for > > >> > > the information they need and appears amateurish. > > >> > > > > >> > > On 2020/05/04 15:13:49, Joshua McKenzie <jmcken...@apache.org> > > wrote: > > >> > > > I've been mulling over this topic the past few days as we often > > >> seem to > > >> > > get > > >> > > > mired in debates over technical details of offerings without a > > clear > > >> > > value > > >> > > > system to weigh them against one another. In the case of > > >> documentation, > > >> > > I'd > > >> > > > propose that we think about this from the perspective of the > users > > >> of the > > >> > > > documentation. I suspect (and would love to hear points of view > > for > > >> or > > >> > > > against this claim as I do not have first-hand knowledge) that > doc > > >> users > > >> > > > would care about the following in this order: > > >> > > > > > >> > > > 1) Correctness > > >> > > > 2) Coverage > > >> > > > 3) Usability and ease of consumption > > >> > > > > > >> > > > Assuming we can get a simple list of traits to optimize for, it > > may > > >> be > > >> > > > helpful to weigh the pros and cons of various documentation > > >> frameworks > > >> > > > against how they facilitate or deliver against those metrics. > For > > >> > > example: > > >> > > > ease of developer ramp and contribution to docs would increase > > >> Coverage, > > >> > > > where more robust tooling and inter-linkage could contribute to > > >> ease of > > >> > > > consumption. > > >> > > > > > >> > > > > > >> > > > > > >> > > > On Fri, May 1, 2020 at 1:52 PM Jon Haddad <j...@jonhaddad.com> > > >> wrote: > > >> > > > > > >> > > > > We've already got Sphinx set up, so you can contribute today. > > >> There's > > >> > > a > > >> > > > > docker container in the `docs` directory and a readme that can > > >> help > > >> > > you get > > >> > > > > started. > > >> > > > > > > >> > > > > On Fri, May 1, 2020 at 10:46 AM Chen-Becker, Derek > > >> > > > > <dchen...@amazon.com.invalid> wrote: > > >> > > > > > > >> > > > > > From the peanut gallery, my main concern is less with the > > >> features > > >> > > of a > > >> > > > > > given markup and more with ensuring that whatever markup/doc > > >> system > > >> > > is > > >> > > > > > used stays mostly out of the way of people who want to > > >> contribute to > > >> > > the > > >> > > > > > docs. I don't want to have to learn a whole publishing > system > > >> just > > >> > > to be > > >> > > > > > able to contribute, whereas minor differences in markup > syntax > > >> seem > > >> > > > > > reasonable. Whatever system ends up getting chosen, is there > > >> > > additional > > >> > > > > > work that can be done to simplify work for writers? I've > used > > >> all > > >> > > three > > >> > > > > > (albeit not in-depth), so I'm willing to help. > > >> > > > > > > > >> > > > > > Derek > > >> > > > > > > > >> > > > > > On 5/1/20 11:08 AM, Jon Haddad wrote: > > >> > > > > > > > >> > > > > > > CAUTION: This email originated from outside of the > > >> organization. > > >> > > Do not > > >> > > > > > click links or open attachments unless you can confirm the > > >> sender and > > >> > > > > know > > >> > > > > > the content is safe. > > >> > > > > > > > > >> > > > > > > > > >> > > > > > > > > >> > > > > > > Apologies, I didn't mean to upset or insult you. My > intent > > >> was to > > >> > > > > > > demonstrate that my opinion is based on experience and I > > >> wasn't > > >> > > > > > suggesting > > >> > > > > > > we switch tooling based on a whim. I also wasn't trying > to > > >> imply > > >> > > you > > >> > > > > > > aren't knowledgeable about writing documentation. > > >> > > > > > > > > >> > > > > > > Apart from this misunderstanding, I think we mostly agree. > > >> I'm not > > >> > > > > > looking > > >> > > > > > > to perform a migration that removes functionality, and the > > >> features > > >> > > > > > you've > > >> > > > > > > listed are all important to keep. Thanks for listing out > > the > > >> bits > > >> > > that > > >> > > > > > are > > >> > > > > > > more complex that I glossed over with my "We write basic > > text > > >> with > > >> > > > > links > > >> > > > > > > and a menu" comment, that was clearly wrong and I > appreciate > > >> the > > >> > > > > > correction. > > >> > > > > > > > > >> > > > > > > Regarding the functionality you listed: > > >> > > > > > > > > >> > > > > > > * Note and warning are both useful features and come built > > >> into > > >> > > > > > > asciidoctor. I made use of them in the TLP documentation > > for > > >> > > > > tlp-cluster > > >> > > > > > > [1] > > >> > > > > > > * I believe the extlinks feature can be replicated easily > > >> using a > > >> > > > > macro. > > >> > > > > > > Here's an example [2]. > > >> > > > > > > * The grammar is a bit more difficult and I don't think > > >> there's a > > >> > > drop > > >> > > > > in > > >> > > > > > > replacement. Writing a block processor [3] would be the > > >> right way > > >> > > to > > >> > > > > > > approach it, I think. > > >> > > > > > > * We'd probably want to set up a configuration for syntax > > >> > > highlighting > > >> > > > > > via > > >> > > > > > > highlight.js (or one of the other supported libs). We can > > >> use the > > >> > > SQL > > >> > > > > > one > > >> > > > > > > [4] as a guide since it's going to be similar to what we > > >> need, and > > >> > > > > > ideally > > >> > > > > > > we would contribute it back for CQL support. > > >> > > > > > > > > >> > > > > > > I agree with you that any migration would at a *minimum* > > need > > >> the > > >> > > above > > >> > > > > > > functionality to be on par with what we already have. A > POC > > >> in a > > >> > > > > branch > > >> > > > > > > displaying a handful of pages (that work with the site > > theme, > > >> > > etc), one > > >> > > > > > of > > >> > > > > > > which is a converted DDL page [5] would suffice, I think, > to > > >> assess > > >> > > > > > whether > > >> > > > > > > or not it's worth the effort. > > >> > > > > > > > > >> > > > > > > No matter which direction we end up going, we still need > to > > >> get > > >> > > > > > > documentation improvements in for 4.0, so it's probably > > worth > > >> > > focusing > > >> > > > > on > > >> > > > > > > that now, and convert to adoc later. I'm happy to get on > a > > >> call > > >> > > soon > > >> > > > > > with > > >> > > > > > > folks who are new to the project documentation to answer > any > > >> > > questions > > >> > > > > > you > > >> > > > > > > all may have. I'm also available to review patches to the > > >> docs, > > >> > > just > > >> > > > > set > > >> > > > > > > me as the reviewer and ping me on Slack. I try to get to > > them > > >> > > within > > >> > > > > > 24h. > > >> > > > > > > > > >> > > > > > > Jon > > >> > > > > > > > > >> > > > > > > [1] http://thelastpickle.com/tlp-cluster/#_setup > > >> > > > > > > [2] > > >> > > > > > > >> https://markhneedham.com/blog/2018/02/19/asciidoctor-creating-macro/ > > >> > > > > > > [3] > > >> > > > > > > > > >> > > > > > > > >> > > > > > > >> > > > > >> > > > https://github.com/asciidoctor/asciidoctorj/blob/v2.1.0/docs/integrator-guide.adoc#blockprocessor > > >> > > > > > > [4] > > >> > > > > > > > > >> > > > > > > > >> > > > > > > >> > > > > >> > > > https://github.com/highlightjs/highlight.js/blob/master/src/languages/sql.js > > >> > > > > > > [5] https://cassandra.apache.org/doc/latest/cql/ddl.html > > >> > > > > > > > > >> > > > > > > On Thu, Apr 30, 2020 at 2:21 PM Sylvain Lebresne < > > >> > > lebre...@gmail.com> > > >> > > > > > wrote: > > >> > > > > > > > > >> > > > > > >> 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 > > >> > > > > > >>>>> > > >> > > > > > > > >> > > > > > > > >> --------------------------------------------------------------------- > > >> > > > > > To unsubscribe, e-mail: > dev-unsubscr...@cassandra.apache.org > > >> > > > > > For additional commands, e-mail: > > dev-h...@cassandra.apache.org > > >> > > > > > > > >> > > > > > > > >> > > > > > > >> > > > > > >> > > > > >> > > > > --------------------------------------------------------------------- > > >> > > To unsubscribe, e-mail: dev-unsubscr...@cassandra.apache.org > > >> > > For additional commands, e-mail: dev-h...@cassandra.apache.org > > >> > > > > >> > > > > >> > > > >> > > >> --------------------------------------------------------------------- > > >> To unsubscribe, e-mail: dev-unsubscr...@cassandra.apache.org > > >> For additional commands, e-mail: dev-h...@cassandra.apache.org > > >> > > >> > > >
