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