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 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
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
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 wrote:
> Great point about it not being hierarchical Paul;
Great point about it not being hierarchical Paul; that logic resonates with
me.
On Wed, May 6, 2020 at 11:50 AM Paul Tepley 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
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
>
> 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.
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
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
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
wrote:
> From the peanut gallery, my main concern is less with the features of a
>
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
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
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
Hi all,
going with asciidoc is a great choice and I can only agree with all
Jon said. It is rich in its capabilities as well as in support and
integration into whatever (browser plugins, IDEA plugins, build
plugins ...).
Even though it is not related to technicalities, I find it important
to
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,
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
+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 wrote:
> I'd like to get the docs out of Sphinx. I hate it. The
I am willing to contribute to this great initiative!
On Fri, Apr 24, 2020 at 8:43 PM Joshua McKenzie
wrote:
> I'm in favor of encouraging low friction / easy doc contributions by using
> generally accepted simple formats (i.e. markdown). Also, if any change in
> doc framework or tooling would
I'm in favor of encouraging low friction / easy doc contributions by using
generally accepted simple formats (i.e. markdown). Also, if any change in
doc framework or tooling would ease adoption of donation + prevent re-work,
that'd be an obvious benefit to deciding on that prior.
On Fri, Apr 24,
> Are there any questions or concerns about this donation?
Getting substantial contributions to the documentation is a great thing to
me
in principle.
My main question was around the exact form this donation would take since
the
project has already lots of documentation. And I was about to
Thanks for coordinating this Josh. Having professional doc writers
contributing regularly to the official docs will be an awesome improvement
to the project. I am definitely looking forward to working with everyone
on this!
On Fri, Apr 24, 2020 at 12:28 PM Joshua McKenzie
wrote:
> >
> > could
>
> could be some duplication.
Absolutely. I was unclear in my original email: this is offered as a
contribution in whatever form best works for the project, and there's
plenty of exceptionally good documentation and work that's already been
done in-tree. The path forward would likely look like
Joshua,
That sounds good. But could be some duplication.
regards,Deepak
On Friday, April 24, 2020, 04:17:07 p.m. UTC, Joshua McKenzie
wrote:
To clarify intent Deepak, we're only talking about donating the Apache
Cassandra portion of the documentation, nothing else. There is no
As a stopgap, Sphinx can generate docs based on markdown (and possibly even
asciidoc but I haven't checked). Probably easiest to do the conversion to
markdown incrementally that way, then we can flip everything over to Hugo.
On Fri, Apr 24, 2020 at 9:17 AM Manish G
wrote:
> I would like to
I would like to contribute here.
Please let me know.
Manish
On Fri, Apr 24, 2020 at 9:03 PM Deepak Vohra wrote:
>
>
> While the DataStax documentation could supplement the Apache Cassandra
> documentation, DataStax is a commercial product based on open source Apache
> Cassandra with
To clarify intent Deepak, we're only talking about donating the Apache
Cassandra portion of the documentation, nothing else. There is no
intention whatsoever for anything DataStax branded or related to merge into
the in-tree project documentation.
On Fri, Apr 24, 2020 at 11:33 AM Deepak Vohra
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
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
27 matches
Mail list logo
