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 a
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 an
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 wha
On Thu, May 14, 2020 at 10:08 PM Joshua McKenzie
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
wro
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; t
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 v
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 u
>
> 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. Hones
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
som
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 th
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
> giv
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 t
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 d
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 high
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
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
+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 synt
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 ea
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, 2
> 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 sugges
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 ta
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
intention
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 cont
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 enhancemen
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
wro
While the DataStax documentation could supplement the Apache Cassandra
documentation, DataStax is a commercial product based on open source Apache
Cassandra with enhancements made to the open source Cassandra. Moreover,
DataStax documentation requires to be maintained and updated and as it is
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
29 matches
Mail list logo
