Sounds good. Thanks everyone for helping drive to a consensus PoV. Excited to see this start to roll in.
On Fri, May 15, 2020 at 12:25 PM Jon Haddad <j...@jonhaddad.com> wrote: > 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 > > > >> > > > >> > > > > > >
