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 > >> > >> >
