You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cassandra.apache.org by Jon Haddad <jo...@jonhaddad.com> on 2020/05/01 17:08:43 UTC
Re: [DISCUSS] Documentation donation
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 <le...@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 <jo...@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 <le...@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 <jo...@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 <jo...@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 <
> > jmckenzie@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
> > > >
> > >
> >
>
Re: [DISCUSS] Documentation donation
Posted by Joshua McKenzie <jm...@apache.org>.
Now that we've got a bit more clarity on our governance model, I was
thinking we could reopen the discussion about doc donations. To preserve
context I figured I'd bring this back up in this thread.
I believe the general points of view I've most recently heard advocated for
by multiple people is as follows:
1) For existing still supported releases (i.e. not trunk), replace existing
docs wholesale w/contribution since there's a lot of holes and ToDo's all
over the existing. Also clean up navigation to them.
2) For trunk / 4.0, change the tool / framework being used (Lorina's
currently PoC'ing that and I think? there's a sufficient consensus there)
and merge in the contribution w/trunk's docs in the new framework
3) We should talk about what we need to do to allow these folks to do their
work at speed without having to constantly interrupt other committers on
the project for merging docs in. A couple folks on the pmc floated the idea
of nominating the full time technical writers to committer so they could
work in tight cycles on the documentation. We could also pair them with
mentors to get through this merge and learn a bit more about project
culture and mores and then go through that process later. No real point of
view I'm advocating for here; attempting to open the discussion
Did I get the above right? Any other positions people are advocating for or
detail to get us aligned?
~Josh
On Fri, May 15, 2020 at 12:59 PM Joshua McKenzie <jm...@apache.org>
wrote:
> 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 <jo...@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 <le...@gmail.com>
>> wrote:
>>
>> > On Thu, May 14, 2020 at 10:08 PM Joshua McKenzie <jm...@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 <jm...@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 <pt...@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 <jm...@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 <ptepley@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 <jm...@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 <jon@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
>> > > >> > > > > <dc...@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 <
>> > > >> > > lebresne@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 <
>> > > >> jon@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 <
>> > > >> > > lebresne@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.sanda@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 <
>> > > >> jon@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 <
>> > > >> > > > > > >>> jmckenzie@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-unsubscribe@cassandra.apache.org
>> > > >> > > > > > For additional commands, e-mail:
>> > > dev-help@cassandra.apache.org
>> > > >> > > > > >
>> > > >> > > > > >
>> > > >> > > > >
>> > > >> > > >
>> > > >> > >
>> > > >> > >
>> > > ---------------------------------------------------------------------
>> > > >> > > To unsubscribe, e-mail: dev-unsubscribe@cassandra.apache.org
>> > > >> > > For additional commands, e-mail: dev-help@cassandra.apache.org
>> > > >> > >
>> > > >> > >
>> > > >> >
>> > > >>
>> > > >>
>> ---------------------------------------------------------------------
>> > > >> To unsubscribe, e-mail: dev-unsubscribe@cassandra.apache.org
>> > > >> For additional commands, e-mail: dev-help@cassandra.apache.org
>> > > >>
>> > > >>
>> > >
>> >
>>
>
Re: [DISCUSS] Documentation donation
Posted by Joshua McKenzie <jm...@apache.org>.
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 <jo...@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 <le...@gmail.com>
> wrote:
>
> > On Thu, May 14, 2020 at 10:08 PM Joshua McKenzie <jm...@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 <jm...@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 <pt...@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 <jm...@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 <pt...@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 <jm...@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 <jo...@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
> > > >> > > > > <dc...@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 <
> > > >> > > lebresne@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 <
> > > >> jon@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 <
> > > >> > > lebresne@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.sanda@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 <
> > > >> jon@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 <
> > > >> > > > > > >>> jmckenzie@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-unsubscribe@cassandra.apache.org
> > > >> > > > > > For additional commands, e-mail:
> > > dev-help@cassandra.apache.org
> > > >> > > > > >
> > > >> > > > > >
> > > >> > > > >
> > > >> > > >
> > > >> > >
> > > >> > >
> > > ---------------------------------------------------------------------
> > > >> > > To unsubscribe, e-mail: dev-unsubscribe@cassandra.apache.org
> > > >> > > For additional commands, e-mail: dev-help@cassandra.apache.org
> > > >> > >
> > > >> > >
> > > >> >
> > > >>
> > > >>
> ---------------------------------------------------------------------
> > > >> To unsubscribe, e-mail: dev-unsubscribe@cassandra.apache.org
> > > >> For additional commands, e-mail: dev-help@cassandra.apache.org
> > > >>
> > > >>
> > >
> >
>
Re: [DISCUSS] Documentation donation
Posted by Jon Haddad <jo...@jonhaddad.com>.
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 <le...@gmail.com> wrote:
> On Thu, May 14, 2020 at 10:08 PM Joshua McKenzie <jm...@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 <jm...@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 <pt...@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 <jm...@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 <pt...@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 <jm...@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 <jo...@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
> > >> > > > > <dc...@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 <
> > >> > > lebresne@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 <
> > >> jon@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 <
> > >> > > lebresne@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.sanda@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 <
> > >> jon@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 <
> > >> > > > > > >>> jmckenzie@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-unsubscribe@cassandra.apache.org
> > >> > > > > > For additional commands, e-mail:
> > dev-help@cassandra.apache.org
> > >> > > > > >
> > >> > > > > >
> > >> > > > >
> > >> > > >
> > >> > >
> > >> > >
> > ---------------------------------------------------------------------
> > >> > > To unsubscribe, e-mail: dev-unsubscribe@cassandra.apache.org
> > >> > > For additional commands, e-mail: dev-help@cassandra.apache.org
> > >> > >
> > >> > >
> > >> >
> > >>
> > >> ---------------------------------------------------------------------
> > >> To unsubscribe, e-mail: dev-unsubscribe@cassandra.apache.org
> > >> For additional commands, e-mail: dev-help@cassandra.apache.org
> > >>
> > >>
> >
>
Re: [DISCUSS] Documentation donation
Posted by Sylvain Lebresne <le...@gmail.com>.
On Thu, May 14, 2020 at 10:08 PM Joshua McKenzie <jm...@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 <jm...@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 <pt...@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 <jm...@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 <pt...@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 <jm...@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 <jo...@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
> >> > > > > <dc...@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 <
> >> > > lebresne@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 <
> >> jon@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 <
> >> > > lebresne@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.sanda@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 <
> >> jon@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 <
> >> > > > > > >>> jmckenzie@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-unsubscribe@cassandra.apache.org
> >> > > > > > For additional commands, e-mail:
> dev-help@cassandra.apache.org
> >> > > > > >
> >> > > > > >
> >> > > > >
> >> > > >
> >> > >
> >> > >
> ---------------------------------------------------------------------
> >> > > To unsubscribe, e-mail: dev-unsubscribe@cassandra.apache.org
> >> > > For additional commands, e-mail: dev-help@cassandra.apache.org
> >> > >
> >> > >
> >> >
> >>
> >> ---------------------------------------------------------------------
> >> To unsubscribe, e-mail: dev-unsubscribe@cassandra.apache.org
> >> For additional commands, e-mail: dev-help@cassandra.apache.org
> >>
> >>
>
Re: [DISCUSS] Documentation donation
Posted by Joshua McKenzie <jm...@apache.org>.
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?
If the latter, how do we unstall it?
On Wed, May 6, 2020 at 3:37 PM Joshua McKenzie <jm...@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 <pt...@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 <jm...@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 <pt...@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 <jm...@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 <jo...@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
>> > > > > <dc...@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 <
>> > > lebresne@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 <
>> jon@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 <
>> > > lebresne@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.sanda@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 <
>> jon@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 <
>> > > > > > >>> jmckenzie@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-unsubscribe@cassandra.apache.org
>> > > > > > For additional commands, e-mail: dev-help@cassandra.apache.org
>> > > > > >
>> > > > > >
>> > > > >
>> > > >
>> > >
>> > > ---------------------------------------------------------------------
>> > > To unsubscribe, e-mail: dev-unsubscribe@cassandra.apache.org
>> > > For additional commands, e-mail: dev-help@cassandra.apache.org
>> > >
>> > >
>> >
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@cassandra.apache.org
>> For additional commands, e-mail: dev-help@cassandra.apache.org
>>
>>
Re: [DISCUSS] Documentation donation
Posted by Joshua McKenzie <jm...@apache.org>.
Great point about it not being hierarchical Paul; that logic resonates with
me.
On Wed, May 6, 2020 at 11:50 AM Paul Tepley <pt...@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 <jm...@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 <pt...@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 <jm...@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 <jo...@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
> > > > > <dc...@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 <
> > > lebresne@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 <jon@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 <
> > > lebresne@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.sanda@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 <
> jon@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 <
> > > > > > >>> jmckenzie@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-unsubscribe@cassandra.apache.org
> > > > > > For additional commands, e-mail: dev-help@cassandra.apache.org
> > > > > >
> > > > > >
> > > > >
> > > >
> > >
> > > ---------------------------------------------------------------------
> > > To unsubscribe, e-mail: dev-unsubscribe@cassandra.apache.org
> > > For additional commands, e-mail: dev-help@cassandra.apache.org
> > >
> > >
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@cassandra.apache.org
> For additional commands, e-mail: dev-help@cassandra.apache.org
>
>
Re: [DISCUSS] Documentation donation
Posted by Paul Tepley <pt...@datastax.com>.
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 <jm...@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 <pt...@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 <jm...@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 <jo...@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
> > > > <dc...@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 <
> > lebresne@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 <jo...@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 <
> > lebresne@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.sanda@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 <jon@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 <
> > > > > >>> jmckenzie@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-unsubscribe@cassandra.apache.org
> > > > > For additional commands, e-mail: dev-help@cassandra.apache.org
> > > > >
> > > > >
> > > >
> > >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@cassandra.apache.org
> > For additional commands, e-mail: dev-help@cassandra.apache.org
> >
> >
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cassandra.apache.org
For additional commands, e-mail: dev-help@cassandra.apache.org
Re: [DISCUSS] Documentation donation
Posted by Joshua McKenzie <jm...@apache.org>.
>
> 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 <pt...@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 <jm...@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 <jo...@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
> > > <dc...@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 <
> lebresne@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 <jo...@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 <
> lebresne@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.sanda@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 <jon@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 <
> > > > >>> jmckenzie@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-unsubscribe@cassandra.apache.org
> > > > For additional commands, e-mail: dev-help@cassandra.apache.org
> > > >
> > > >
> > >
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@cassandra.apache.org
> For additional commands, e-mail: dev-help@cassandra.apache.org
>
>
Re: [DISCUSS] Documentation donation
Posted by Paul Tepley <pt...@datastax.com>.
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 <jm...@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 <jo...@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
> > <dc...@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 <le...@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 <jo...@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 <lebresne@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 <jo...@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 <jo...@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 <
> > > >>> jmckenzie@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-unsubscribe@cassandra.apache.org
> > > For additional commands, e-mail: dev-help@cassandra.apache.org
> > >
> > >
> >
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cassandra.apache.org
For additional commands, e-mail: dev-help@cassandra.apache.org
Re: [DISCUSS] Documentation donation
Posted by Joshua McKenzie <jm...@apache.org>.
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 <jo...@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
> <dc...@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 <le...@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 <jo...@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 <lebresne@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 <jo...@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 <jo...@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 <
> > >>> jmckenzie@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-unsubscribe@cassandra.apache.org
> > For additional commands, e-mail: dev-help@cassandra.apache.org
> >
> >
>
Re: [DISCUSS] Documentation donation
Posted by Jon Haddad <jo...@jonhaddad.com>.
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
<dc...@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 <le...@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 <jo...@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 <le...@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 <jo...@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 <jo...@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 <
> >>> jmckenzie@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-unsubscribe@cassandra.apache.org
> For additional commands, e-mail: dev-help@cassandra.apache.org
>
>
Re: [DISCUSS] Documentation donation
Posted by "Chen-Becker, Derek" <dc...@amazon.com.INVALID>.
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 <le...@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 <jo...@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 <le...@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 <jo...@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 <jo...@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 <
>>> jmckenzie@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-unsubscribe@cassandra.apache.org
For additional commands, e-mail: dev-help@cassandra.apache.org