RE: A JIRA proposing a seperate repository for the online documentation

[Kenneth Brotman]

I've been trying to withdraw from the conversation since Friday.

-Original Message-
From: Josh McKenzie [mailto:jmcken...@apache.org] 
Sent: Monday, March 19, 2018 9:56 AM
To: dev@cassandra.apache.org
Subject: Re: A JIRA proposing a seperate repository for the online documentation

And to be explicit about this: I'm going to withdraw from this conversation 
now. I don't think we're generating sufficient signal in this dialog compared 
to the noise.

Thanks for the enthusiasm and input Kenneth.

On Mon, Mar 19, 2018 at 11:48 AM, Josh McKenzie <jmcken...@apache.org>
wrote:

> You missed the point ...  let them do it their way when it makes no
>> difference
>
> If you're suggesting we use a static markdown based generator as the 
> "go to" method for content generation and accept PR's for "New 
> Hotness" (do it their way), then sure, that seems a totally fair 
> compromise. Pretty sure that's not what you're suggesting, and people 
> Wild Westing a contribution to a project, that the project then owns 
> when you get bored of it and move on, doesn't qualify for "makes no 
> difference".
>
> On Mon, Mar 19, 2018 at 11:10 AM, Kenneth Brotman < 
> kenbrot...@yahoo.com.invalid> wrote:
>
>> You missed the point.  If someone can do a good job on something, 
>> just let them do it their way when it makes no difference.  
>> Specifically regarding the website, I should be able to submit HTML, 
>> CSS and JS if I want, others should be able to do it with the static 
>> generator thing if they want.  I could have fixed the website with 
>> complete version specific pages, with some really good text to fill 
>> in where there is none now and so on; and done that several different 
>> ways by now.  I'm donating my time too.  Please keep that in mind.
>>
>> Let me ask again, where are the standards?  How can you leave the 
>> website for the project you will be associated with looking that substandard?
>> Rahul Singh has been making a very important point that different 
>> types of uses with different uses cases use the website. This is a 
>> public website; not an internal site for coders.
>>
>> Kenneth Brotman
>>
>> -Original Message-
>> From: Josh McKenzie [mailto:jmcken...@apache.org]
>> Sent: Monday, March 19, 2018 7:42 AM
>> To: dev@cassandra.apache.org
>> Subject: Re: A JIRA proposing a seperate repository for the online 
>> documentation
>>
>> Wow. Ok, let's try this again.
>>
>> Josh, you made my point for me.   Lower the barriers to entry
>>
>> Kenneth, I disagree. The C* community is not expressing universal 
>> interest in having a hand-crafted bespoke website, but many have 
>> expressed being open to using markdown to create content. Former: 
>> high barrier to entry *for the community as a whole, not just you.* 
>> Important distinction.
>>
>> If someone like me offers to knock out something that's been a 
>> problem for
>> > the group and can do a very professional job, next time get out of 
>> > the
>> way.
>>
>> It's been a problem because people haven't devoted time to it, not 
>> because they couldn't figure out markdown. The Apache Way is about 
>> consensus, not telling people to get out of the way when they don't 
>> agree with you.
>>
>> I don't make junk Josh.
>>
>> Actions speak louder than words and thus far your tone, 
>> combativeness, and repeated unwillingness to acknowledge what looks 
>> to be a strong general consensus from your peers is the evidence we have to 
>> go on.
>>
>> On Mon, Mar 19, 2018 at 10:21 AM, Kenneth Brotman < 
>> kenbrot...@yahoo.com.invalid> wrote:
>>
>> > Josh, you made my point for me.   Lower the barriers to entry, not throw
>> > extra steps I don’t need at me.  If someone like me offers to knock 
>> > out something that's been a problem for the group and can do a very 
>> > professional job, next time get out of the way.  I don't make junk Josh.
>> > Sorry that Apache is not interested in a site with multi-media 
>> > support; or even sites with complete pages.  Show me one quality 
>> > open source Apache site.  Wake up.  Raise your bar!  Engineers 
>> > shouldn't speak in the language of mediocrity.
>> >
>> > Kenneth Brotman
>> >
>> > -Original Message-
>> > From: Josh McKenzie [mailto:jmcken...@apache.org]
>> > Sent: Monday, March 19, 2018 5:27 AM
>> > To: dev@cassandra.apache.org
>> > Subject: Re: A JIRA proposing a seperate repository for the online 
>> > 

Re: A JIRA proposing a seperate repository for the online documentation

[Josh McKenzie]

And to be explicit about this: I'm going to withdraw from this conversation
now. I don't think we're generating sufficient signal in this dialog
compared to the noise.

Thanks for the enthusiasm and input Kenneth.

On Mon, Mar 19, 2018 at 11:48 AM, Josh McKenzie <jmcken...@apache.org>
wrote:

> You missed the point ...  let them do it their way when it makes no
>> difference
>
> If you're suggesting we use a static markdown based generator as the "go
> to" method for content generation and accept PR's for "New Hotness" (do it
> their way), then sure, that seems a totally fair compromise. Pretty sure
> that's not what you're suggesting, and people Wild Westing a contribution
> to a project, that the project then owns when you get bored of it and move
> on, doesn't qualify for "makes no difference".
>
> On Mon, Mar 19, 2018 at 11:10 AM, Kenneth Brotman <
> kenbrot...@yahoo.com.invalid> wrote:
>
>> You missed the point.  If someone can do a good job on something, just
>> let them do it their way when it makes no difference.  Specifically
>> regarding the website, I should be able to submit HTML, CSS and JS if I
>> want, others should be able to do it with the static generator thing if
>> they want.  I could have fixed the website with complete version specific
>> pages, with some really good text to fill in where there is none now and so
>> on; and done that several different ways by now.  I'm donating my time
>> too.  Please keep that in mind.
>>
>> Let me ask again, where are the standards?  How can you leave the website
>> for the project you will be associated with looking that substandard?
>> Rahul Singh has been making a very important point that different types of
>> uses with different uses cases use the website. This is a public website;
>> not an internal site for coders.
>>
>> Kenneth Brotman
>>
>> -----Original Message-----
>> From: Josh McKenzie [mailto:jmcken...@apache.org]
>> Sent: Monday, March 19, 2018 7:42 AM
>> To: dev@cassandra.apache.org
>> Subject: Re: A JIRA proposing a seperate repository for the online
>> documentation
>>
>> Wow. Ok, let's try this again.
>>
>> Josh, you made my point for me.   Lower the barriers to entry
>>
>> Kenneth, I disagree. The C* community is not expressing universal
>> interest in having a hand-crafted bespoke website, but many have expressed
>> being open to using markdown to create content. Former: high barrier to
>> entry *for the community as a whole, not just you.* Important distinction.
>>
>> If someone like me offers to knock out something that's been a problem for
>> > the group and can do a very professional job, next time get out of the
>> way.
>>
>> It's been a problem because people haven't devoted time to it, not
>> because they couldn't figure out markdown. The Apache Way is about
>> consensus, not telling people to get out of the way when they don't agree
>> with you.
>>
>> I don't make junk Josh.
>>
>> Actions speak louder than words and thus far your tone, combativeness,
>> and repeated unwillingness to acknowledge what looks to be a strong general
>> consensus from your peers is the evidence we have to go on.
>>
>> On Mon, Mar 19, 2018 at 10:21 AM, Kenneth Brotman <
>> kenbrot...@yahoo.com.invalid> wrote:
>>
>> > Josh, you made my point for me.   Lower the barriers to entry, not throw
>> > extra steps I don’t need at me.  If someone like me offers to knock
>> > out something that's been a problem for the group and can do a very
>> > professional job, next time get out of the way.  I don't make junk Josh.
>> > Sorry that Apache is not interested in a site with multi-media
>> > support; or even sites with complete pages.  Show me one quality open
>> > source Apache site.  Wake up.  Raise your bar!  Engineers shouldn't
>> > speak in the language of mediocrity.
>> >
>> > Kenneth Brotman
>> >
>> > -Original Message-
>> > From: Josh McKenzie [mailto:jmcken...@apache.org]
>> > Sent: Monday, March 19, 2018 5:27 AM
>> > To: dev@cassandra.apache.org
>> > Subject: Re: A JIRA proposing a seperate repository for the online
>> > documentation
>> >
>> > >
>> > > I've been writing html a long time; since about 1990.  You're asking
>> > > me to learn a weird little program, a static site generator just to
>> > > change something I can already do without using a program at all.
>> >
>> > You're one person among a community of back-en

Re: A JIRA proposing a seperate repository for the online documentation

[Josh McKenzie]

>
> You missed the point ...  let them do it their way when it makes no
> difference

If you're suggesting we use a static markdown based generator as the "go
to" method for content generation and accept PR's for "New Hotness" (do it
their way), then sure, that seems a totally fair compromise. Pretty sure
that's not what you're suggesting, and people Wild Westing a contribution
to a project, that the project then owns when you get bored of it and move
on, doesn't qualify for "makes no difference".

On Mon, Mar 19, 2018 at 11:10 AM, Kenneth Brotman <
kenbrot...@yahoo.com.invalid> wrote:

> You missed the point.  If someone can do a good job on something, just let
> them do it their way when it makes no difference.  Specifically regarding
> the website, I should be able to submit HTML, CSS and JS if I want, others
> should be able to do it with the static generator thing if they want.  I
> could have fixed the website with complete version specific pages, with
> some really good text to fill in where there is none now and so on; and
> done that several different ways by now.  I'm donating my time too.  Please
> keep that in mind.
>
> Let me ask again, where are the standards?  How can you leave the website
> for the project you will be associated with looking that substandard?
> Rahul Singh has been making a very important point that different types of
> uses with different uses cases use the website. This is a public website;
> not an internal site for coders.
>
> Kenneth Brotman
>
> -Original Message-
> From: Josh McKenzie [mailto:jmcken...@apache.org]
> Sent: Monday, March 19, 2018 7:42 AM
> To: dev@cassandra.apache.org
> Subject: Re: A JIRA proposing a seperate repository for the online
> documentation
>
> Wow. Ok, let's try this again.
>
> Josh, you made my point for me.   Lower the barriers to entry
>
> Kenneth, I disagree. The C* community is not expressing universal interest
> in having a hand-crafted bespoke website, but many have expressed being
> open to using markdown to create content. Former: high barrier to entry
> *for the community as a whole, not just you.* Important distinction.
>
> If someone like me offers to knock out something that's been a problem for
> > the group and can do a very professional job, next time get out of the
> way.
>
> It's been a problem because people haven't devoted time to it, not because
> they couldn't figure out markdown. The Apache Way is about consensus, not
> telling people to get out of the way when they don't agree with you.
>
> I don't make junk Josh.
>
> Actions speak louder than words and thus far your tone, combativeness, and
> repeated unwillingness to acknowledge what looks to be a strong general
> consensus from your peers is the evidence we have to go on.
>
> On Mon, Mar 19, 2018 at 10:21 AM, Kenneth Brotman <
> kenbrot...@yahoo.com.invalid> wrote:
>
> > Josh, you made my point for me.   Lower the barriers to entry, not throw
> > extra steps I don’t need at me.  If someone like me offers to knock
> > out something that's been a problem for the group and can do a very
> > professional job, next time get out of the way.  I don't make junk Josh.
> > Sorry that Apache is not interested in a site with multi-media
> > support; or even sites with complete pages.  Show me one quality open
> > source Apache site.  Wake up.  Raise your bar!  Engineers shouldn't
> > speak in the language of mediocrity.
> >
> > Kenneth Brotman
> >
> > -Original Message-
> > From: Josh McKenzie [mailto:jmcken...@apache.org]
> > Sent: Monday, March 19, 2018 5:27 AM
> > To: dev@cassandra.apache.org
> > Subject: Re: A JIRA proposing a seperate repository for the online
> > documentation
> >
> > >
> > > I've been writing html a long time; since about 1990.  You're asking
> > > me to learn a weird little program, a static site generator just to
> > > change something I can already do without using a program at all.
> >
> > You're one person among a community of back-end Java devs. If you want
> > people to contribute to things you need to lower the barriers to
> > entry, not deep-dive into some bespoke thing that may never see the
> > light of day and, when completed, misses the mark on what users of
> cassandra care about:
> > clarity and speed. Also: bus-factor 1 is bad.
> >
> > Another weird thing: Wouldn't we want a website that is dynamic and
> > > multi-media rich?
> >
> > Personally? No. We're talking function here, not form. As an engineer,
> > I don't want to wade through someone else's idea of what "dynamic and
> > multi-medi

RE: A JIRA proposing a seperate repository for the online documentation

[Kenneth Brotman]

You missed the point.  If someone can do a good job on something, just let them 
do it their way when it makes no difference.  Specifically regarding the 
website, I should be able to submit HTML, CSS and JS if I want, others should 
be able to do it with the static generator thing if they want.  I could have 
fixed the website with complete version specific pages, with some really good 
text to fill in where there is none now and so on; and done that several 
different ways by now.  I'm donating my time too.  Please keep that in mind.  

Let me ask again, where are the standards?  How can you leave the website for 
the project you will be associated with looking that substandard?  Rahul Singh 
has been making a very important point that different types of uses with 
different uses cases use the website. This is a public website; not an internal 
site for coders.

Kenneth Brotman

-Original Message-
From: Josh McKenzie [mailto:jmcken...@apache.org] 
Sent: Monday, March 19, 2018 7:42 AM
To: dev@cassandra.apache.org
Subject: Re: A JIRA proposing a seperate repository for the online documentation

Wow. Ok, let's try this again.

Josh, you made my point for me.   Lower the barriers to entry

Kenneth, I disagree. The C* community is not expressing universal interest in 
having a hand-crafted bespoke website, but many have expressed being open to 
using markdown to create content. Former: high barrier to entry *for the 
community as a whole, not just you.* Important distinction.

If someone like me offers to knock out something that's been a problem for
> the group and can do a very professional job, next time get out of the way.

It's been a problem because people haven't devoted time to it, not because they 
couldn't figure out markdown. The Apache Way is about consensus, not telling 
people to get out of the way when they don't agree with you.

I don't make junk Josh.

Actions speak louder than words and thus far your tone, combativeness, and 
repeated unwillingness to acknowledge what looks to be a strong general 
consensus from your peers is the evidence we have to go on.

On Mon, Mar 19, 2018 at 10:21 AM, Kenneth Brotman < 
kenbrot...@yahoo.com.invalid> wrote:

> Josh, you made my point for me.   Lower the barriers to entry, not throw
> extra steps I don’t need at me.  If someone like me offers to knock 
> out something that's been a problem for the group and can do a very 
> professional job, next time get out of the way.  I don't make junk Josh.
> Sorry that Apache is not interested in a site with multi-media 
> support; or even sites with complete pages.  Show me one quality open 
> source Apache site.  Wake up.  Raise your bar!  Engineers shouldn't 
> speak in the language of mediocrity.
>
> Kenneth Brotman
>
> -Original Message-
> From: Josh McKenzie [mailto:jmcken...@apache.org]
> Sent: Monday, March 19, 2018 5:27 AM
> To: dev@cassandra.apache.org
> Subject: Re: A JIRA proposing a seperate repository for the online 
> documentation
>
> >
> > I've been writing html a long time; since about 1990.  You're asking 
> > me to learn a weird little program, a static site generator just to 
> > change something I can already do without using a program at all.
>
> You're one person among a community of back-end Java devs. If you want 
> people to contribute to things you need to lower the barriers to 
> entry, not deep-dive into some bespoke thing that may never see the 
> light of day and, when completed, misses the mark on what users of cassandra 
> care about:
> clarity and speed. Also: bus-factor 1 is bad.
>
> Another weird thing: Wouldn't we want a website that is dynamic and
> > multi-media rich?
>
> Personally? No. We're talking function here, not form. As an engineer, 
> I don't want to wade through someone else's idea of what "dynamic and 
> multi-media rich" means when I'm trying to find an answer to something 
> or learn something so I can get on with my job.
>
>
>
> On Sun, Mar 18, 2018 at 5:12 PM, Nate McCall <zznat...@gmail.com> wrote:
>
> > On Mon, Mar 19, 2018 at 12:41 AM, Kenneth Brotman 
> > <kenbrot...@yahoo.com.invalid> wrote:
> > > I don't know what we are doing for the website technologies right 
> > > now
> > because like everything else what we do is not documented anywhere.
> > Where are the servers: the cloud?  What server software are we 
> > running?  How is the html, etc. generated and published?  How is 
> > search
> done for the website?
> >
> > http://cassandra.apache.org/doc/latest/development/documentation.htm
> > l The resulting static HTML from Sphinx is hosted on ASF 
> > infrastructure.
> >
> > 
> > - To unsubscribe, e-ma

Re: A JIRA proposing a seperate repository for the online documentation

[Josh McKenzie]

Wow. Ok, let's try this again.

Josh, you made my point for me.   Lower the barriers to entry

Kenneth, I disagree. The C* community is not expressing universal interest
in having a hand-crafted bespoke website, but many have expressed being
open to using markdown to create content. Former: high barrier to entry *for
the community as a whole, not just you.* Important distinction.

If someone like me offers to knock out something that's been a problem for
> the group and can do a very professional job, next time get out of the way.

It's been a problem because people haven't devoted time to it, not because
they couldn't figure out markdown. The Apache Way is about consensus, not
telling people to get out of the way when they don't agree with you.

I don't make junk Josh.

Actions speak louder than words and thus far your tone, combativeness, and
repeated unwillingness to acknowledge what looks to be a strong general
consensus from your peers is the evidence we have to go on.

On Mon, Mar 19, 2018 at 10:21 AM, Kenneth Brotman <
kenbrot...@yahoo.com.invalid> wrote:

> Josh, you made my point for me.   Lower the barriers to entry, not throw
> extra steps I don’t need at me.  If someone like me offers to knock out
> something that's been a problem for the group and can do a very
> professional job, next time get out of the way.  I don't make junk Josh.
> Sorry that Apache is not interested in a site with multi-media support; or
> even sites with complete pages.  Show me one quality open source Apache
> site.  Wake up.  Raise your bar!  Engineers shouldn't speak in the language
> of mediocrity.
>
> Kenneth Brotman
>
> -Original Message-
> From: Josh McKenzie [mailto:jmcken...@apache.org]
> Sent: Monday, March 19, 2018 5:27 AM
> To: dev@cassandra.apache.org
> Subject: Re: A JIRA proposing a seperate repository for the online
> documentation
>
> >
> > I've been writing html a long time; since about 1990.  You're asking
> > me to learn a weird little program, a static site generator just to
> > change something I can already do without using a program at all.
>
> You're one person among a community of back-end Java devs. If you want
> people to contribute to things you need to lower the barriers to entry, not
> deep-dive into some bespoke thing that may never see the light of day and,
> when completed, misses the mark on what users of cassandra care about:
> clarity and speed. Also: bus-factor 1 is bad.
>
> Another weird thing: Wouldn't we want a website that is dynamic and
> > multi-media rich?
>
> Personally? No. We're talking function here, not form. As an engineer, I
> don't want to wade through someone else's idea of what "dynamic and
> multi-media rich" means when I'm trying to find an answer to something or
> learn something so I can get on with my job.
>
>
>
> On Sun, Mar 18, 2018 at 5:12 PM, Nate McCall <zznat...@gmail.com> wrote:
>
> > On Mon, Mar 19, 2018 at 12:41 AM, Kenneth Brotman
> > <kenbrot...@yahoo.com.invalid> wrote:
> > > I don't know what we are doing for the website technologies right
> > > now
> > because like everything else what we do is not documented anywhere.
> > Where are the servers: the cloud?  What server software are we
> > running?  How is the html, etc. generated and published?  How is search
> done for the website?
> >
> > http://cassandra.apache.org/doc/latest/development/documentation.html
> > The resulting static HTML from Sphinx is hosted on ASF infrastructure.
> >
> > -
> > To unsubscribe, e-mail: dev-unsubscr...@cassandra.apache.org
> > For additional commands, e-mail: dev-h...@cassandra.apache.org
> >
> >
>
>
> -
> To unsubscribe, e-mail: dev-unsubscr...@cassandra.apache.org
> For additional commands, e-mail: dev-h...@cassandra.apache.org
>
>

RE: A JIRA proposing a seperate repository for the online documentation

[Kenneth Brotman]

Josh, you made my point for me.   Lower the barriers to entry, not throw extra 
steps I don’t need at me.  If someone like me offers to knock out something 
that's been a problem for the group and can do a very professional job, next 
time get out of the way.  I don't make junk Josh.  Sorry that Apache is not 
interested in a site with multi-media support; or even sites with complete 
pages.  Show me one quality open source Apache site.  Wake up.  Raise your bar! 
 Engineers shouldn't speak in the language of mediocrity.

Kenneth Brotman  

-Original Message-
From: Josh McKenzie [mailto:jmcken...@apache.org] 
Sent: Monday, March 19, 2018 5:27 AM
To: dev@cassandra.apache.org
Subject: Re: A JIRA proposing a seperate repository for the online documentation

>
> I've been writing html a long time; since about 1990.  You're asking 
> me to learn a weird little program, a static site generator just to 
> change something I can already do without using a program at all.

You're one person among a community of back-end Java devs. If you want people 
to contribute to things you need to lower the barriers to entry, not deep-dive 
into some bespoke thing that may never see the light of day and, when 
completed, misses the mark on what users of cassandra care about:
clarity and speed. Also: bus-factor 1 is bad.

Another weird thing: Wouldn't we want a website that is dynamic and
> multi-media rich?

Personally? No. We're talking function here, not form. As an engineer, I don't 
want to wade through someone else's idea of what "dynamic and multi-media rich" 
means when I'm trying to find an answer to something or learn something so I 
can get on with my job.



On Sun, Mar 18, 2018 at 5:12 PM, Nate McCall <zznat...@gmail.com> wrote:

> On Mon, Mar 19, 2018 at 12:41 AM, Kenneth Brotman 
> <kenbrot...@yahoo.com.invalid> wrote:
> > I don't know what we are doing for the website technologies right 
> > now
> because like everything else what we do is not documented anywhere.  
> Where are the servers: the cloud?  What server software are we 
> running?  How is the html, etc. generated and published?  How is search done 
> for the website?
>
> http://cassandra.apache.org/doc/latest/development/documentation.html
> The resulting static HTML from Sphinx is hosted on ASF infrastructure.
>
> -
> To unsubscribe, e-mail: dev-unsubscr...@cassandra.apache.org
> For additional commands, e-mail: dev-h...@cassandra.apache.org
>
>


-
To unsubscribe, e-mail: dev-unsubscr...@cassandra.apache.org
For additional commands, e-mail: dev-h...@cassandra.apache.org

Re: A JIRA proposing a seperate repository for the online documentation

[Josh McKenzie]

>
> I've been writing html a long time; since about 1990.  You're asking me to
> learn a weird little program, a static site generator just to change
> something I can already do without using a program at all.

You're one person among a community of back-end Java devs. If you want
people to contribute to things you need to lower the barriers to entry, not
deep-dive into some bespoke thing that may never see the light of day and,
when completed, misses the mark on what users of cassandra care about:
clarity and speed. Also: bus-factor 1 is bad.

Another weird thing: Wouldn't we want a website that is dynamic and
> multi-media rich?

Personally? No. We're talking function here, not form. As an engineer, I
don't want to wade through someone else's idea of what "dynamic and
multi-media rich" means when I'm trying to find an answer to something or
learn something so I can get on with my job.



On Sun, Mar 18, 2018 at 5:12 PM, Nate McCall  wrote:

> On Mon, Mar 19, 2018 at 12:41 AM, Kenneth Brotman
>  wrote:
> > I don't know what we are doing for the website technologies right now
> because like everything else what we do is not documented anywhere.  Where
> are the servers: the cloud?  What server software are we running?  How is
> the html, etc. generated and published?  How is search done for the website?
>
> http://cassandra.apache.org/doc/latest/development/documentation.html
> The resulting static HTML from Sphinx is hosted on ASF infrastructure.
>
> -
> To unsubscribe, e-mail: dev-unsubscr...@cassandra.apache.org
> For additional commands, e-mail: dev-h...@cassandra.apache.org
>
>

Re: A JIRA proposing a seperate repository for the online documentation

[Nate McCall]

On Mon, Mar 19, 2018 at 12:41 AM, Kenneth Brotman
 wrote:
> I don't know what we are doing for the website technologies right now because 
> like everything else what we do is not documented anywhere.  Where are the 
> servers: the cloud?  What server software are we running?  How is the html, 
> etc. generated and published?  How is search done for the website?

http://cassandra.apache.org/doc/latest/development/documentation.html
The resulting static HTML from Sphinx is hosted on ASF infrastructure.

-
To unsubscribe, e-mail: dev-unsubscr...@cassandra.apache.org
For additional commands, e-mail: dev-h...@cassandra.apache.org

RE: A JIRA proposing a seperate repository for the online documentation

[Kenneth Brotman]

The answer is right before us:  Let's use Rahul Singh's Awesome Cassandra list 
for now: https://github.com/anant/awesome-cassandra  while he works on some 
other things for us.  I will be submitting contributions to it regularly and 
referencing it as the go to resource.  It will serve us well for now.

Kenneth Brotman

-Original Message-
From: Kenneth Brotman [mailto:kenbrot...@yahoo.com.INVALID] 
Sent: Sunday, March 18, 2018 4:41 AM
To: dev@cassandra.apache.org
Subject: RE: A JIRA proposing a seperate repository for the online documentation

I don't know what we are doing for the website technologies right now because 
like everything else what we do is not documented anywhere.  Where are the 
servers: the cloud?  What server software are we running?  How is the html, 
etc. generated and published?  How is search done for the website?

Kenneth Brotman


-Original Message-
From: Rahul Singh [mailto:rahul.xavier.si...@gmail.com]
Sent: Saturday, March 17, 2018 7:12 AM
To: dev@cassandra.apache.org
Subject: RE: A JIRA proposing a seperate repository for the online documentation

Static site generator just takes content from flat files or apis (that can be 
managed from a headless cms) and creates static files or progressive web apps 
that are optimized for speed. Nothing to do with multi-media or dynamic in 
terms of client side javascript / css. It’s just an old technology with a new 
name. Thats how we used to generate sites back in 1990s.. :)

--
Rahul Singh
rahul.si...@anant.us

Anant Corporation

On Mar 17, 2018, 10:03 AM -0400, Kenneth Brotman 
<kenbrot...@yahoo.com.invalid>, wrote:
> How about if we look at the website a little differently. Isn't it an 
> opportunity to showcase Cassandra and related technologies like search! 
> Shouldn't we be an extraordinary advocate and example of the technology 
> ourselves?
>
> Rahul, your comment on the different users with different use cases was very 
> wise.
>
> I've been writing html a long time; since about 1990. You're asking me to 
> learn a weird little program, a static site generator just to change 
> something I can already do without using a program at all.
>
> Another weird thing: Wouldn't we want a website that is dynamic and 
> multi-media rich?
>
> Kenneth Brotman
>
>
> -Original Message-
> From: Rahul Singh [mailto:rahul.xavier.si...@gmail.com]
> Sent: Saturday, March 17, 2018 5:57 AM
> To: dev@cassandra.apache.org
> Subject: RE: A JIRA proposing a seperate repository for the online 
> documentation
>
> I’ve previously deep dived into Static Site generators and there are numerous 
> ones.
>
> http://leaves.anant.us/#!/leaf/7255?tag=static.site
>
> I don’t like changing technology for the sake of change. I think it’s a 
> stupid waste of time. In one hand I agree, the substance is more important 
> than the form. On the other hand. I [insert f-bomb] hate writing HTML / CSS, 
> or restructured text. Markdown is much easier. Hugo is one of many that if 
> setup right, it can save a ton of time and make it more accessible for people 
> to contribute.
>
> There is a difference however in developer documentation for developers of 
> cassandra, user documentation for cassandra users, documentation for and 
> administrators. They are different users and have different use cases Some 
> need reference style docs, others need guides.
>
> Some good examples, (the software quality not-withstanding), correlate with 
> software propularity are Wordpress. I am not wild about Wordpress, but their 
> codex.wordpress.org has been generally a good “user doc.”
>
> Envision the outcome even if you have to mimic someone else. I don’t mind 
> stealing/copying if it gets us one step further than we are. The reaper docs 
> look easy to maintain and I could care less about Hugo, Hexo, Jekyll, Hyde, 
> KafkasMom, EinsteinsDog, ShrodingersCat static site generator.
>
> I think action should come before decision in open source. Prove something 
> before suggesting a change. Jon’s reaper example is good. If anyone has 
> something better, show it. Prove it.
>
> --
> Rahul Singh
> rahul.si...@anant.us
>
> Anant Corporation
>
> On Mar 16, 2018, 6:54 PM -0400, Kenneth Brotman 
> <kenbrotman@yahoo.cominvalid>, wrote:
> > There is no need for another program. Keep the code in html, css and js 
> > People can modify that and show proposed changes in that. No need to 
> > convert back and forth from other formats. If someone is doing something 
> > more involved, they probably already have a program themselves.
> >
> > -Original Message-
> > From: beggles...@apple.com [mailto:beggles...@apple.com]
> > Sent: Friday, March 16, 2018 3:16 PM
> > To: dev@cassandra.apache.org
> > Subject: Re: A J

RE: A JIRA proposing a seperate repository for the online documentation

[Kenneth Brotman]

I don't know what we are doing for the website technologies right now because 
like everything else what we do is not documented anywhere.  Where are the 
servers: the cloud?  What server software are we running?  How is the html, 
etc. generated and published?  How is search done for the website?

Kenneth Brotman


-Original Message-
From: Rahul Singh [mailto:rahul.xavier.si...@gmail.com] 
Sent: Saturday, March 17, 2018 7:12 AM
To: dev@cassandra.apache.org
Subject: RE: A JIRA proposing a seperate repository for the online documentation

Static site generator just takes content from flat files or apis (that can be 
managed from a headless cms) and creates static files or progressive web apps 
that are optimized for speed. Nothing to do with multi-media or dynamic in 
terms of client side javascript / css. It’s just an old technology with a new 
name. Thats how we used to generate sites back in 1990s.. :)

--
Rahul Singh
rahul.si...@anant.us

Anant Corporation

On Mar 17, 2018, 10:03 AM -0400, Kenneth Brotman 
<kenbrot...@yahoo.com.invalid>, wrote:
> How about if we look at the website a little differently. Isn't it an 
> opportunity to showcase Cassandra and related technologies like search! 
> Shouldn't we be an extraordinary advocate and example of the technology 
> ourselves?
>
> Rahul, your comment on the different users with different use cases was very 
> wise.
>
> I've been writing html a long time; since about 1990. You're asking me to 
> learn a weird little program, a static site generator just to change 
> something I can already do without using a program at all.
>
> Another weird thing: Wouldn't we want a website that is dynamic and 
> multi-media rich?
>
> Kenneth Brotman
>
>
> -Original Message-
> From: Rahul Singh [mailto:rahul.xavier.si...@gmail.com]
> Sent: Saturday, March 17, 2018 5:57 AM
> To: dev@cassandra.apache.org
> Subject: RE: A JIRA proposing a seperate repository for the online 
> documentation
>
> I’ve previously deep dived into Static Site generators and there are numerous 
> ones.
>
> http://leaves.anant.us/#!/leaf/7255?tag=static.site
>
> I don’t like changing technology for the sake of change. I think it’s a 
> stupid waste of time. In one hand I agree, the substance is more important 
> than the form. On the other hand. I [insert f-bomb] hate writing HTML / CSS, 
> or restructured text. Markdown is much easier. Hugo is one of many that if 
> setup right, it can save a ton of time and make it more accessible for people 
> to contribute.
>
> There is a difference however in developer documentation for developers of 
> cassandra, user documentation for cassandra users, documentation for and 
> administrators. They are different users and have different use cases Some 
> need reference style docs, others need guides.
>
> Some good examples, (the software quality not-withstanding), correlate with 
> software propularity are Wordpress. I am not wild about Wordpress, but their 
> codex.wordpress.org has been generally a good “user doc.”
>
> Envision the outcome even if you have to mimic someone else. I don’t mind 
> stealing/copying if it gets us one step further than we are. The reaper docs 
> look easy to maintain and I could care less about Hugo, Hexo, Jekyll, Hyde, 
> KafkasMom, EinsteinsDog, ShrodingersCat static site generator.
>
> I think action should come before decision in open source. Prove something 
> before suggesting a change. Jon’s reaper example is good. If anyone has 
> something better, show it. Prove it.
>
> --
> Rahul Singh
> rahul.si...@anant.us
>
> Anant Corporation
>
> On Mar 16, 2018, 6:54 PM -0400, Kenneth Brotman 
> <kenbrotman@yahoo.cominvalid>, wrote:
> > There is no need for another program. Keep the code in html, css and js 
> > People can modify that and show proposed changes in that. No need to 
> > convert back and forth from other formats. If someone is doing something 
> > more involved, they probably already have a program themselves.
> >
> > -Original Message-
> > From: beggles...@apple.com [mailto:beggles...@apple.com]
> > Sent: Friday, March 16, 2018 3:16 PM
> > To: dev@cassandra.apache.org
> > Subject: Re: A JIRA proposing a seperate repository for the online 
> > documentation
> >
> > It would probably be more productive to list some specific concerns you 
> > have with Hugo. Then explain why you think they make using it a bad idea 
> > Then offer some alternatives.
> >
> > On 3/16/18, 1:18 PM, "Kenneth Brotman" <kenbrot...@yahoo.com.INVALID> wrote:
> >
> > Thanks for that Eric Evans.
> >
> > I'm not sure Hugo is the way to go. I don't see how I would generate the 
> &

RE: A JIRA proposing a seperate repository for the online documentation

[Rahul Singh]

Static site generator just takes content from flat files or apis (that can be 
managed from a headless cms) and creates static files or progressive web apps 
that are optimized for speed. Nothing to do with multi-media or dynamic in 
terms of client side javascript / css. It’s just an old technology with a new 
name. Thats how we used to generate sites back in 1990s.. :)

--
Rahul Singh
rahul.si...@anant.us

Anant Corporation

On Mar 17, 2018, 10:03 AM -0400, Kenneth Brotman 
<kenbrot...@yahoo.com.invalid>, wrote:
> How about if we look at the website a little differently. Isn't it an 
> opportunity to showcase Cassandra and related technologies like search! 
> Shouldn't we be an extraordinary advocate and example of the technology 
> ourselves?
>
> Rahul, your comment on the different users with different use cases was very 
> wise.
>
> I've been writing html a long time; since about 1990. You're asking me to 
> learn a weird little program, a static site generator just to change 
> something I can already do without using a program at all.
>
> Another weird thing: Wouldn't we want a website that is dynamic and 
> multi-media rich?
>
> Kenneth Brotman
>
>
> -Original Message-
> From: Rahul Singh [mailto:rahul.xavier.si...@gmail.com]
> Sent: Saturday, March 17, 2018 5:57 AM
> To: dev@cassandra.apache.org
> Subject: RE: A JIRA proposing a seperate repository for the online 
> documentation
>
> I’ve previously deep dived into Static Site generators and there are numerous 
> ones.
>
> http://leaves.anant.us/#!/leaf/7255?tag=static.site
>
> I don’t like changing technology for the sake of change. I think it’s a 
> stupid waste of time. In one hand I agree, the substance is more important 
> than the form. On the other hand. I [insert f-bomb] hate writing HTML / CSS, 
> or restructured text. Markdown is much easier. Hugo is one of many that if 
> setup right, it can save a ton of time and make it more accessible for people 
> to contribute.
>
> There is a difference however in developer documentation for developers of 
> cassandra, user documentation for cassandra users, documentation for and 
> administrators. They are different users and have different use cases. Some 
> need reference style docs, others need guides.
>
> Some good examples, (the software quality not-withstanding), correlate with 
> software propularity are Wordpress. I am not wild about Wordpress, but their 
> codex.wordpress.org has been generally a good “user doc.”
>
> Envision the outcome even if you have to mimic someone else. I don’t mind 
> stealing/copying if it gets us one step further than we are. The reaper docs 
> look easy to maintain and I could care less about Hugo, Hexo, Jekyll, Hyde, 
> KafkasMom, EinsteinsDog, ShrodingersCat static site generator.
>
> I think action should come before decision in open source. Prove something 
> before suggesting a change. Jon’s reaper example is good. If anyone has 
> something better, show it. Prove it.
>
> --
> Rahul Singh
> rahul.si...@anant.us
>
> Anant Corporation
>
> On Mar 16, 2018, 6:54 PM -0400, Kenneth Brotman 
> <kenbrot...@yahoo.com.invalid>, wrote:
> > There is no need for another program. Keep the code in html, css and js 
> > People can modify that and show proposed changes in that. No need to 
> > convert back and forth from other formats. If someone is doing something 
> > more involved, they probably already have a program themselves.
> >
> > -Original Message-
> > From: beggles...@apple.com [mailto:beggles...@apple.com]
> > Sent: Friday, March 16, 2018 3:16 PM
> > To: dev@cassandra.apache.org
> > Subject: Re: A JIRA proposing a seperate repository for the online
> > documentation
> >
> > It would probably be more productive to list some specific concerns you 
> > have with Hugo. Then explain why you think they make using it a bad idea 
> > Then offer some alternatives.
> >
> > On 3/16/18, 1:18 PM, "Kenneth Brotman" <kenbrot...@yahoo.com.INVALID> wrote:
> >
> > Thanks for that Eric Evans.
> >
> > I'm not sure Hugo is the way to go. I don't see how I would generate the 
> > quality of work I would want with it. It seems like another example of 
> > coders learning and using a more complicated program to generate the code 
> > they could have already generated - it’s a disease in the I.T. industry 
> > right now. But I could be wrong.
> >
> > Here's the thing. I've been spending a lot of my time for the past three 
> > weeks now trying to help with the website. That is a tiny website. I've 
> > never worked with a website that tiny. Bear with me.
> >
> > I'm stud

RE: A JIRA proposing a seperate repository for the online documentation

[Kenneth Brotman]

How about if we look at the website a little differently.  Isn't it an 
opportunity to showcase Cassandra and related technologies like search!  
Shouldn't we be an extraordinary advocate and example of the technology 
ourselves?  

Rahul, your comment on the different users with different use cases was very 
wise.  

I've been writing html a long time; since about 1990.  You're asking me to 
learn a weird little program, a static site generator just to change something 
I can already do without using a program at all.  

Another weird thing: Wouldn't we want a website that is dynamic and multi-media 
rich?

Kenneth Brotman


-Original Message-
From: Rahul Singh [mailto:rahul.xavier.si...@gmail.com] 
Sent: Saturday, March 17, 2018 5:57 AM
To: dev@cassandra.apache.org
Subject: RE: A JIRA proposing a seperate repository for the online documentation

I’ve previously deep dived into Static Site generators and there are numerous 
ones.

http://leaves.anant.us/#!/leaf/7255?tag=static.site

I don’t like changing technology for the sake of change. I think it’s a stupid 
waste of time. In one hand I agree, the substance is more important than the 
form. On the other hand. I [insert f-bomb] hate writing HTML / CSS, or 
restructured text. Markdown is much easier. Hugo is one of many that if setup 
right, it can save a ton of time and make it more accessible for people to 
contribute.

There is a difference however in developer documentation for developers of 
cassandra, user documentation for cassandra users, documentation for and 
administrators. They are different users and have different use cases. Some 
need reference style docs, others need guides.

Some good examples, (the software quality not-withstanding), correlate with 
software propularity are Wordpress. I am not wild about Wordpress, but their 
codex.wordpress.org has been generally a good “user doc.”

Envision the outcome even if you have to mimic someone else. I don’t mind 
stealing/copying if it gets us one step further than we are. The reaper docs 
look easy to maintain and I could care less about Hugo, Hexo, Jekyll, Hyde, 
KafkasMom, EinsteinsDog, ShrodingersCat static site generator.

I think action should come before decision in open source. Prove something 
before suggesting a change. Jon’s reaper example is good. If anyone has 
something better, show it. Prove it.

--
Rahul Singh
rahul.si...@anant.us

Anant Corporation

On Mar 16, 2018, 6:54 PM -0400, Kenneth Brotman <kenbrot...@yahoo.com.invalid>, 
wrote:
> There is no need for another program. Keep the code in html, css and js 
> People can modify that and show proposed changes in that. No need to convert 
> back and forth from other formats. If someone is doing something more 
> involved, they probably already have a program themselves.
>
> -Original Message-
> From: beggles...@apple.com [mailto:beggles...@apple.com]
> Sent: Friday, March 16, 2018 3:16 PM
> To: dev@cassandra.apache.org
> Subject: Re: A JIRA proposing a seperate repository for the online 
> documentation
>
> It would probably be more productive to list some specific concerns you have 
> with Hugo. Then explain why you think they make using it a bad idea Then 
> offer some alternatives.
>
> On 3/16/18, 1:18 PM, "Kenneth Brotman" <kenbrot...@yahoo.com.INVALID> wrote:
>
> Thanks for that Eric Evans.
>
> I'm not sure Hugo is the way to go. I don't see how I would generate the 
> quality of work I would want with it. It seems like another example of coders 
> learning and using a more complicated program to generate the code they could 
> have already generated - it’s a disease in the I.T. industry right now. But I 
> could be wrong.
>
> Here's the thing. I've been spending a lot of my time for the past three 
> weeks now trying to help with the website. That is a tiny website. I've never 
> worked with a website that tiny. Bear with me.
>
> I'm studying Jeff Carpenter and Eben Hewitt's book: Cassandra The Definitive 
> Guide 
> https://www.amazon.com/Cassandra-Definitive-Guide-Distributed-Scale/dp/1491933666/ref=sr_1_1?ie=UTF8=1521230539=8-1=cassandra+the+definitive+guide
>  and have already have a terrible itch to start contributing some code. I 
> just want to get set up to do that. The book seems to be a good way to get 
> familiar with the internals and the code of Cassandra.
>
> I can only do so much for the group at one time just like anyone else. I'll 
> only do top quality work. I'll only be a part of top quality work. It could 
> be that I won't feel comfortable with what the group wants to do for the 
> website.
>
> Please keep working on it as it is really embarrassing, terrible, substandard 
> unacceptable beneath professional standards...
>
> I will contribute if it's possible for me to do so. Let's see what we decide 
> to do going forward f

RE: A JIRA proposing a seperate repository for the online documentation

[Rahul Singh]

I’ve previously deep dived into Static Site generators and there are numerous 
ones.

http://leaves.anant.us/#!/leaf/7255?tag=static.site

I don’t like changing technology for the sake of change. I think it’s a stupid 
waste of time. In one hand I agree, the substance is more important than the 
form. On the other hand. I [insert f-bomb] hate writing HTML / CSS, or 
restructured text. Markdown is much easier. Hugo is one of many that if setup 
right, it can save a ton of time and make it more accessible for people to 
contribute.

There is a difference however in developer documentation for developers of 
cassandra, user documentation for cassandra users, documentation for and 
administrators. They are different users and have different use cases. Some 
need reference style docs, others need guides.

Some good examples, (the software quality not-withstanding), correlate with 
software propularity are Wordpress. I am not wild about Wordpress, but their 
codex.wordpress.org has been generally a good “user doc.”

Envision the outcome even if you have to mimic someone else. I don’t mind 
stealing/copying if it gets us one step further than we are. The reaper docs 
look easy to maintain and I could care less about Hugo, Hexo, Jekyll, Hyde, 
KafkasMom, EinsteinsDog, ShrodingersCat static site generator.

I think action should come before decision in open source. Prove something 
before suggesting a change. Jon’s reaper example is good. If anyone has 
something better, show it. Prove it.

--
Rahul Singh
rahul.si...@anant.us

Anant Corporation

On Mar 16, 2018, 6:54 PM -0400, Kenneth Brotman <kenbrot...@yahoo.com.invalid>, 
wrote:
> There is no need for another program. Keep the code in html, css and js. 
> People can modify that and show proposed changes in that. No need to convert 
> back and forth from other formats. If someone is doing something more 
> involved, they probably already have a program themselves.
>
> -Original Message-
> From: beggles...@apple.com [mailto:beggles...@apple.com]
> Sent: Friday, March 16, 2018 3:16 PM
> To: dev@cassandra.apache.org
> Subject: Re: A JIRA proposing a seperate repository for the online 
> documentation
>
> It would probably be more productive to list some specific concerns you have 
> with Hugo. Then explain why you think they make using it a bad idea. Then 
> offer some alternatives.
>
> On 3/16/18, 1:18 PM, "Kenneth Brotman" <kenbrot...@yahoo.com.INVALID> wrote:
>
> Thanks for that Eric Evans.
>
> I'm not sure Hugo is the way to go. I don't see how I would generate the 
> quality of work I would want with it. It seems like another example of coders 
> learning and using a more complicated program to generate the code they could 
> have already generated - it’s a disease in the I.T. industry right now. But I 
> could be wrong.
>
> Here's the thing. I've been spending a lot of my time for the past three 
> weeks now trying to help with the website. That is a tiny website. I've never 
> worked with a website that tiny. Bear with me.
>
> I'm studying Jeff Carpenter and Eben Hewitt's book: Cassandra The Definitive 
> Guide 
> https://www.amazon.com/Cassandra-Definitive-Guide-Distributed-Scale/dp/1491933666/ref=sr_1_1?ie=UTF8=1521230539=8-1=cassandra+the+definitive+guide
>  and have already have a terrible itch to start contributing some code. I 
> just want to get set up to do that. The book seems to be a good way to get 
> familiar with the internals and the code of Cassandra.
>
> I can only do so much for the group at one time just like anyone else. I'll 
> only do top quality work. I'll only be a part of top quality work. It could 
> be that I won't feel comfortable with what the group wants to do for the 
> website.
>
> Please keep working on it as it is really embarrassing, terrible, substandard 
> unacceptable beneath professional standards...
>
> I will contribute if it's possible for me to do so. Let's see what we decide 
> to do going forward for the website.
>
> Kenneth Brotman
> (Cassandra coder?)
>
> -Original Message-
> From: Eric Evans [mailto:john.eric.ev...@gmail.com]
> Sent: Friday, March 16, 2018 7:59 AM
> To: dev@cassandra.apache.org
> Subject: Re: A JIRA proposing a seperate repository for the online 
> documentation
>
> On Thu, Mar 15, 2018 at 11:40 AM, Kenneth Brotman 
> <kenbrotman@yahoo.cominvalid> wrote:
> > Well pickle my cucumbers Jon! It's good to know that you have experience 
> > with Hugo, see it as a good fit and that all has been well. I look forward 
> > to the jira epic!
> >
> > How exactly does the group make such a decision: Call for final discussion? 
> > Call for vote? Wait for the PMC to vote?
>
> Good question!
>
> Decisions like this are made by consensus; As 

Re: A JIRA proposing a seperate repository for the online documentation

[Blake Eggleston]

It would probably be more productive to list some specific concerns you have 
with Hugo. Then explain why you think they make using it a bad idea. Then offer 
some alternatives.

On 3/16/18, 1:18 PM, "Kenneth Brotman" <kenbrot...@yahoo.com.INVALID> wrote:

Thanks for that Eric Evans.  

I'm not sure Hugo is the way to go.  I don't see how I would generate the 
quality of work I would want with it.  It seems like another example of coders 
learning and using a more complicated program to generate the code they could 
have already generated - it’s a disease in the I.T. industry right now.  But I 
could be wrong.  

Here's the thing.  I've been spending a lot of my time for the past three 
weeks now trying to help with the website.  That is a tiny website.  I've never 
worked with a website that tiny.  Bear with me.  

I'm studying Jeff Carpenter and Eben Hewitt's book: Cassandra The 
Definitive Guide 
https://www.amazon.com/Cassandra-Definitive-Guide-Distributed-Scale/dp/1491933666/ref=sr_1_1?ie=UTF8=1521230539=8-1=cassandra+the+definitive+guide
 and have already have a terrible itch to start contributing some code.  I just 
want to get set up to do that.  The book seems to be a good way to get familiar 
with the internals and the code of Cassandra.

I can only do so much for the group at one time just like anyone else.  
I'll only do top quality work.  I'll only be a part of top quality work.  It 
could be that I won't feel comfortable with what the group wants to do for the 
website.  

Please keep working on it as it is really embarrassing, terrible, 
substandard unacceptable beneath professional standards...

I will contribute if it's possible for me to do so. Let's see what we 
decide to do going forward for the website.

Kenneth Brotman
(Cassandra coder?) 

-Original Message-
From: Eric Evans [mailto:john.eric.ev...@gmail.com] 
Sent: Friday, March 16, 2018 7:59 AM
To: dev@cassandra.apache.org
    Subject: Re: A JIRA proposing a seperate repository for the online 
documentation

On Thu, Mar 15, 2018 at 11:40 AM, Kenneth Brotman 
<kenbrot...@yahoo.com.invalid> wrote:
> Well pickle my cucumbers Jon!  It's good to know that you have experience 
with Hugo, see it as a good fit and that all has been well.  I look forward to 
the jira epic!
>
> How exactly does the group make such a decision:  Call for final 
discussion?  Call for vote?  Wait for the PMC to vote?

Good question!

Decisions like this are made by consensus; As the person who is attempting 
to do something, you discuss your ideas with the group, listen to the feedback 
of others, and develop consensus around a direction.

This is more difficult than demanding your way, or having someone(s) in a 
position of absolute power tell you what you can and cannot do, but the result 
is better.


> -Original Message-
> From: Jon Haddad [mailto:jonathan.had...@gmail.com] On Behalf Of Jon 
> Haddad
> Sent: Thursday, March 15, 2018 9:24 AM
> To: dev@cassandra.apache.org
    > Subject: Re: A JIRA proposing a seperate repository for the online 
> documentation
>
> Murukesh is correct on a very useable, pretty standard process of 
multi-versioned docs.
>
> I’ll put my thoughts in a JIRA epic tonight.  I’ll be a multi-phase 
process.  Also correct in that I’d like us to move to Hugo for the site, I’d 
like us to have a unified system between the site & the docs, and hugo has been 
excellent. We run the reaper site & docs off hugo, it works well.  We just 
don’t do multi-versions (because we don’t support multiple): 
https://github.com/thelastpickle/cassandra-reaper/tree/master/src/docs 
<https://github.com/thelastpickle/cassandra-reaper/tree/master/src/docs>.
>
> Jon
>
>> On Mar 15, 2018, at 8:57 AM, Murukesh Mohanan 
<murukesh.moha...@gmail.com> wrote:
>>
>> On Fri, Mar 16, 2018 at 0:19 Kenneth Brotman 
>> <kenbrot...@yahoo.com.invalid <mailto:kenbrot...@yahoo.com.invalid>>
>> wrote:
>>
>>> Help me out here.  I could have had a website with support for more 
>>> than one version done several different ways by now.
>>>
>>> A website with several versions of documentation is going to have 
>>> sub-directories for each version of documentation obviously.  I've 
>>> offered to create those sub-directories under the "doc" folder of 
>>> the current repository; and I've offered to move the online 
>>> documentation to a separate repository and have the sub-directories 
>>> there.  Both were shot down.  Is there a third way?  If so please just 
spill the beans.
>&g

RE: A JIRA proposing a seperate repository for the online documentation

[Kenneth Brotman]

Thanks for that Eric Evans.  

I'm not sure Hugo is the way to go.  I don't see how I would generate the 
quality of work I would want with it.  It seems like another example of coders 
learning and using a more complicated program to generate the code they could 
have already generated - it’s a disease in the I.T. industry right now.  But I 
could be wrong.  

Here's the thing.  I've been spending a lot of my time for the past three weeks 
now trying to help with the website.  That is a tiny website.  I've never 
worked with a website that tiny.  Bear with me.  

I'm studying Jeff Carpenter and Eben Hewitt's book: Cassandra The Definitive 
Guide 
https://www.amazon.com/Cassandra-Definitive-Guide-Distributed-Scale/dp/1491933666/ref=sr_1_1?ie=UTF8=1521230539=8-1=cassandra+the+definitive+guide
 and have already have a terrible itch to start contributing some code.  I just 
want to get set up to do that.  The book seems to be a good way to get familiar 
with the internals and the code of Cassandra.

I can only do so much for the group at one time just like anyone else.  I'll 
only do top quality work.  I'll only be a part of top quality work.  It could 
be that I won't feel comfortable with what the group wants to do for the 
website.  

Please keep working on it as it is really embarrassing, terrible, substandard 
unacceptable beneath professional standards...

I will contribute if it's possible for me to do so. Let's see what we decide to 
do going forward for the website.

Kenneth Brotman
(Cassandra coder?) 

-Original Message-
From: Eric Evans [mailto:john.eric.ev...@gmail.com] 
Sent: Friday, March 16, 2018 7:59 AM
To: dev@cassandra.apache.org
Subject: Re: A JIRA proposing a seperate repository for the online documentation

On Thu, Mar 15, 2018 at 11:40 AM, Kenneth Brotman 
<kenbrot...@yahoo.com.invalid> wrote:
> Well pickle my cucumbers Jon!  It's good to know that you have experience 
> with Hugo, see it as a good fit and that all has been well.  I look forward 
> to the jira epic!
>
> How exactly does the group make such a decision:  Call for final discussion?  
> Call for vote?  Wait for the PMC to vote?

Good question!

Decisions like this are made by consensus; As the person who is attempting to 
do something, you discuss your ideas with the group, listen to the feedback of 
others, and develop consensus around a direction.

This is more difficult than demanding your way, or having someone(s) in a 
position of absolute power tell you what you can and cannot do, but the result 
is better.


> -Original Message-
> From: Jon Haddad [mailto:jonathan.had...@gmail.com] On Behalf Of Jon 
> Haddad
> Sent: Thursday, March 15, 2018 9:24 AM
> To: dev@cassandra.apache.org
> Subject: Re: A JIRA proposing a seperate repository for the online 
> documentation
>
> Murukesh is correct on a very useable, pretty standard process of 
> multi-versioned docs.
>
> I’ll put my thoughts in a JIRA epic tonight.  I’ll be a multi-phase process.  
> Also correct in that I’d like us to move to Hugo for the site, I’d like us to 
> have a unified system between the site & the docs, and hugo has been 
> excellent. We run the reaper site & docs off hugo, it works well.  We just 
> don’t do multi-versions (because we don’t support multiple): 
> https://github.com/thelastpickle/cassandra-reaper/tree/master/src/docs 
> <https://github.com/thelastpickle/cassandra-reaper/tree/master/src/docs>.
>
> Jon
>
>> On Mar 15, 2018, at 8:57 AM, Murukesh Mohanan <murukesh.moha...@gmail.com> 
>> wrote:
>>
>> On Fri, Mar 16, 2018 at 0:19 Kenneth Brotman 
>> <kenbrot...@yahoo.com.invalid <mailto:kenbrot...@yahoo.com.invalid>>
>> wrote:
>>
>>> Help me out here.  I could have had a website with support for more 
>>> than one version done several different ways by now.
>>>
>>> A website with several versions of documentation is going to have 
>>> sub-directories for each version of documentation obviously.  I've 
>>> offered to create those sub-directories under the "doc" folder of 
>>> the current repository; and I've offered to move the online 
>>> documentation to a separate repository and have the sub-directories 
>>> there.  Both were shot down.  Is there a third way?  If so please just 
>>> spill the beans.
>>>
>>
>> There is. Note that the website is an independent repository. So to 
>> host docs for multiple versions, only the website's repository (or 
>> rather, the final built contents) needs multiple directories. You can 
>> just checkout each branch or tag, generate the docs, make a directory 
>> for that branch or tag in the website repo, and copy the generated 
>> docs there with appropriate modifications.
>>

Re: A JIRA proposing a seperate repository for the online documentation

[Eric Evans]

On Thu, Mar 15, 2018 at 11:40 AM, Kenneth Brotman
<kenbrot...@yahoo.com.invalid> wrote:
> Well pickle my cucumbers Jon!  It's good to know that you have experience 
> with Hugo, see it as a good fit and that all has been well.  I look forward 
> to the jira epic!
>
> How exactly does the group make such a decision:  Call for final discussion?  
> Call for vote?  Wait for the PMC to vote?

Good question!

Decisions like this are made by consensus; As the person who is
attempting to do something, you discuss your ideas with the group,
listen to the feedback of others, and develop consensus around a
direction.

This is more difficult than demanding your way, or having someone(s)
in a position of absolute power tell you what you can and cannot do,
but the result is better.


> -Original Message-
> From: Jon Haddad [mailto:jonathan.had...@gmail.com] On Behalf Of Jon Haddad
> Sent: Thursday, March 15, 2018 9:24 AM
> To: dev@cassandra.apache.org
> Subject: Re: A JIRA proposing a seperate repository for the online 
> documentation
>
> Murukesh is correct on a very useable, pretty standard process of 
> multi-versioned docs.
>
> I’ll put my thoughts in a JIRA epic tonight.  I’ll be a multi-phase process.  
> Also correct in that I’d like us to move to Hugo for the site, I’d like us to 
> have a unified system between the site & the docs, and hugo has been 
> excellent. We run the reaper site & docs off hugo, it works well.  We just 
> don’t do multi-versions (because we don’t support multiple): 
> https://github.com/thelastpickle/cassandra-reaper/tree/master/src/docs 
> <https://github.com/thelastpickle/cassandra-reaper/tree/master/src/docs>.
>
> Jon
>
>> On Mar 15, 2018, at 8:57 AM, Murukesh Mohanan <murukesh.moha...@gmail.com> 
>> wrote:
>>
>> On Fri, Mar 16, 2018 at 0:19 Kenneth Brotman
>> <kenbrot...@yahoo.com.invalid <mailto:kenbrot...@yahoo.com.invalid>>
>> wrote:
>>
>>> Help me out here.  I could have had a website with support for more
>>> than one version done several different ways by now.
>>>
>>> A website with several versions of documentation is going to have
>>> sub-directories for each version of documentation obviously.  I've
>>> offered to create those sub-directories under the "doc" folder of the
>>> current repository; and I've offered to move the online documentation
>>> to a separate repository and have the sub-directories there.  Both
>>> were shot down.  Is there a third way?  If so please just spill the beans.
>>>
>>
>> There is. Note that the website is an independent repository. So to
>> host docs for multiple versions, only the website's repository (or
>> rather, the final built contents) needs multiple directories. You can
>> just checkout each branch or tag, generate the docs, make a directory
>> for that branch or tag in the website repo, and copy the generated
>> docs there with appropriate modifications.
>>
>> I do this on a smaller scale using GitHub Pages (repo:
>> https://github.com/murukeshm/cassandra 
>> <https://github.com/murukeshm/cassandra> site:
>> https://murukeshm.github.io/cassandra/
>> <https://murukeshm.github.io/cassandra/>
>> <https://murukeshm.github.io/cassandra/3.11.1/
>> <https://murukeshm.github.io/cassandra/3.11.1/>> ). The method is a
>> bit hacky as I noted in CASSANDRA-13907. A daily cronjobs updated the repo 
>> if docs are updated. 3.9+ versions are available.
>>
>>
>>
>>
>>> Also, no offense to anyone at Sphinx but for a project our size it's
>>> not suitable.  We need to move off it now.  It's a problem.
>>>
>>> Can we go past this and on to the documenting!  Please help resolve this.
>>>
>>> How are we going to:
>>> Make the submission of code changes include required changes to
>>> documentation including the online documentation?
>>> Allow, encourage the online documentation to publish multiple
>>> versions of documentation concurrently including all officially supported 
>>> versions?
>>
>>
>> Only on this point: we'll need to start by improving the website build
>> process. Michael's comment on 13907 (
>> https://issues.apache.org/jira/browse/CASSANDRA-13907?focusedCommentId
>> =16211365=com.atlassian.jira.plugin.system.issuetabpanels:comment
>> -tabpanel#comment-16211365
>> <https://issues.apache.org/jira/browse/CASSANDRA-13907?focusedCommentI
>> d=16211365=com.atlassian.jira.plugin.system.issuetabpanels:commen
>> t-tabpanel#comment-16211365>
>> )
>> shows it's a 

RE: A JIRA proposing a seperate repository for the online documentation

[Kenneth Brotman]

Well pickle my cucumbers Jon!  It's good to know that you have experience with 
Hugo, see it as a good fit and that all has been well.  I look forward to the 
jira epic!  

How exactly does the group make such a decision:  Call for final discussion?  
Call for vote?  Wait for the PMC to vote?  

Kenneth Brotman

-Original Message-
From: Jon Haddad [mailto:jonathan.had...@gmail.com] On Behalf Of Jon Haddad
Sent: Thursday, March 15, 2018 9:24 AM
To: dev@cassandra.apache.org
Subject: Re: A JIRA proposing a seperate repository for the online documentation

Murukesh is correct on a very useable, pretty standard process of 
multi-versioned docs.

I’ll put my thoughts in a JIRA epic tonight.  I’ll be a multi-phase process.  
Also correct in that I’d like us to move to Hugo for the site, I’d like us to 
have a unified system between the site & the docs, and hugo has been excellent. 
We run the reaper site & docs off hugo, it works well.  We just don’t do 
multi-versions (because we don’t support multiple): 
https://github.com/thelastpickle/cassandra-reaper/tree/master/src/docs 
<https://github.com/thelastpickle/cassandra-reaper/tree/master/src/docs>. 

Jon

> On Mar 15, 2018, at 8:57 AM, Murukesh Mohanan <murukesh.moha...@gmail.com> 
> wrote:
> 
> On Fri, Mar 16, 2018 at 0:19 Kenneth Brotman 
> <kenbrot...@yahoo.com.invalid <mailto:kenbrot...@yahoo.com.invalid>>
> wrote:
> 
>> Help me out here.  I could have had a website with support for more 
>> than one version done several different ways by now.
>> 
>> A website with several versions of documentation is going to have 
>> sub-directories for each version of documentation obviously.  I've 
>> offered to create those sub-directories under the "doc" folder of the 
>> current repository; and I've offered to move the online documentation 
>> to a separate repository and have the sub-directories there.  Both 
>> were shot down.  Is there a third way?  If so please just spill the beans.
>> 
> 
> There is. Note that the website is an independent repository. So to 
> host docs for multiple versions, only the website's repository (or 
> rather, the final built contents) needs multiple directories. You can 
> just checkout each branch or tag, generate the docs, make a directory 
> for that branch or tag in the website repo, and copy the generated 
> docs there with appropriate modifications.
> 
> I do this on a smaller scale using GitHub Pages (repo:
> https://github.com/murukeshm/cassandra 
> <https://github.com/murukeshm/cassandra> site:
> https://murukeshm.github.io/cassandra/ 
> <https://murukeshm.github.io/cassandra/>
> <https://murukeshm.github.io/cassandra/3.11.1/ 
> <https://murukeshm.github.io/cassandra/3.11.1/>> ). The method is a 
> bit hacky as I noted in CASSANDRA-13907. A daily cronjobs updated the repo if 
> docs are updated. 3.9+ versions are available.
> 
> 
> 
> 
>> Also, no offense to anyone at Sphinx but for a project our size it's 
>> not suitable.  We need to move off it now.  It's a problem.
>> 
>> Can we go past this and on to the documenting!  Please help resolve this.
>> 
>> How are we going to:
>> Make the submission of code changes include required changes to 
>> documentation including the online documentation?
>> Allow, encourage the online documentation to publish multiple 
>> versions of documentation concurrently including all officially supported 
>> versions?
> 
> 
> Only on this point: we'll need to start by improving the website build 
> process. Michael's comment on 13907 (
> https://issues.apache.org/jira/browse/CASSANDRA-13907?focusedCommentId
> =16211365=com.atlassian.jira.plugin.system.issuetabpanels:comment
> -tabpanel#comment-16211365 
> <https://issues.apache.org/jira/browse/CASSANDRA-13907?focusedCommentI
> d=16211365=com.atlassian.jira.plugin.system.issuetabpanels:commen
> t-tabpanel#comment-16211365>
> )
> shows it's a painful, fiddly process. That seems to be the main 
> blocker. I think Jon has shown interest in moving to Hugo from the 
> current Jekyll setup.
> 
> 
> 
>> Move our project onto a more suitable program than Sphinx for our needs?
>> 
>> Kenneth Brotman
>> 
>> -Original Message-
>> From: Eric Evans [mailto:john.eric.ev...@gmail.com]
>> Sent: Thursday, March 15, 2018 7:50 AM
>> To: dev@cassandra.apache.org
>> Subject: Re: A JIRA proposing a seperate repository for the online 
>> documentation
>> 
>> On Thu, Mar 15, 2018 at 4:58 AM, Rahul Singh 
>> <rahul.xavier.si...@gmail.com>
>> wrote:
>>> 
>>> I don’t understand why it’s so complicated. In tree docs

Re: A JIRA proposing a seperate repository for the online documentation

[Jon Haddad]

Murukesh is correct on a very useable, pretty standard process of 
multi-versioned docs.

I’ll put my thoughts in a JIRA epic tonight.  I’ll be a multi-phase process.  
Also correct in that I’d like us to move to Hugo for the site, I’d like us to 
have a unified system between the site & the docs, and hugo has been excellent. 
We run the reaper site & docs off hugo, it works well.  We just don’t do 
multi-versions (because we don’t support multiple): 
https://github.com/thelastpickle/cassandra-reaper/tree/master/src/docs 
<https://github.com/thelastpickle/cassandra-reaper/tree/master/src/docs>. 

Jon

> On Mar 15, 2018, at 8:57 AM, Murukesh Mohanan <murukesh.moha...@gmail.com> 
> wrote:
> 
> On Fri, Mar 16, 2018 at 0:19 Kenneth Brotman <kenbrot...@yahoo.com.invalid 
> <mailto:kenbrot...@yahoo.com.invalid>>
> wrote:
> 
>> Help me out here.  I could have had a website with support for more than
>> one version done several different ways by now.
>> 
>> A website with several versions of documentation is going to have
>> sub-directories for each version of documentation obviously.  I've offered
>> to create those sub-directories under the "doc" folder of the current
>> repository; and I've offered to move the online documentation to a separate
>> repository and have the sub-directories there.  Both were shot down.  Is
>> there a third way?  If so please just spill the beans.
>> 
> 
> There is. Note that the website is an independent repository. So to host
> docs for multiple versions, only the website's repository (or rather, the
> final built contents) needs multiple directories. You can just checkout
> each branch or tag, generate the docs, make a directory for that branch or
> tag in the website repo, and copy the generated docs there with appropriate
> modifications.
> 
> I do this on a smaller scale using GitHub Pages (repo:
> https://github.com/murukeshm/cassandra 
> <https://github.com/murukeshm/cassandra> site:
> https://murukeshm.github.io/cassandra/ 
> <https://murukeshm.github.io/cassandra/>
> <https://murukeshm.github.io/cassandra/3.11.1/ 
> <https://murukeshm.github.io/cassandra/3.11.1/>> ). The method is a bit
> hacky as I noted in CASSANDRA-13907. A daily cronjobs updated the repo if
> docs are updated. 3.9+ versions are available.
> 
> 
> 
> 
>> Also, no offense to anyone at Sphinx but for a project our size it's not
>> suitable.  We need to move off it now.  It's a problem.
>> 
>> Can we go past this and on to the documenting!  Please help resolve this.
>> 
>> How are we going to:
>> Make the submission of code changes include required changes to
>> documentation including the online documentation?
>> Allow, encourage the online documentation to publish multiple versions of
>> documentation concurrently including all officially supported versions?
> 
> 
> Only on this point: we'll need to start by improving the website build
> process. Michael's comment on 13907 (
> https://issues.apache.org/jira/browse/CASSANDRA-13907?focusedCommentId=16211365=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-16211365
>  
> <https://issues.apache.org/jira/browse/CASSANDRA-13907?focusedCommentId=16211365=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-16211365>
> )
> shows it's a painful, fiddly process. That seems to be the main blocker. I
> think Jon has shown interest in moving to Hugo from the current Jekyll
> setup.
> 
> 
> 
>> Move our project onto a more suitable program than Sphinx for our needs?
>> 
>> Kenneth Brotman
>> 
>> -Original Message-
>> From: Eric Evans [mailto:john.eric.ev...@gmail.com]
>> Sent: Thursday, March 15, 2018 7:50 AM
>> To: dev@cassandra.apache.org
>> Subject: Re: A JIRA proposing a seperate repository for the online
>> documentation
>> 
>> On Thu, Mar 15, 2018 at 4:58 AM, Rahul Singh <rahul.xavier.si...@gmail.com>
>> wrote:
>>> 
>>> I don’t understand why it’s so complicated. In tree docs are as good as
>> any. All the old docs are there in the version control system.
>>> 
>>> All we need to is a) generate docs for old versions b) improve user
>> experience on the site by having it clearly laid out what is latest vs. old
>> docs and c) have some semblance of a search maybe using something like
>> Algolia or whatever.
>> 
>> This.
>> 
>> Keeping the docs in-tree is a huge win, because they can move in lock-step
>> with changes occurring in that branch/version.  I don't think we've been
>> enforcing this, but code-changes that a

Re: A JIRA proposing a seperate repository for the online documentation

[Murukesh Mohanan]

On Fri, Mar 16, 2018 at 0:19 Kenneth Brotman <kenbrot...@yahoo.com.invalid>
wrote:

> Help me out here.  I could have had a website with support for more than
> one version done several different ways by now.
>
> A website with several versions of documentation is going to have
> sub-directories for each version of documentation obviously.  I've offered
> to create those sub-directories under the "doc" folder of the current
> repository; and I've offered to move the online documentation to a separate
> repository and have the sub-directories there.  Both were shot down.  Is
> there a third way?  If so please just spill the beans.
>

There is. Note that the website is an independent repository. So to host
docs for multiple versions, only the website's repository (or rather, the
final built contents) needs multiple directories. You can just checkout
each branch or tag, generate the docs, make a directory for that branch or
tag in the website repo, and copy the generated docs there with appropriate
modifications.

I do this on a smaller scale using GitHub Pages (repo:
https://github.com/murukeshm/cassandra site:
https://murukeshm.github.io/cassandra/
<https://murukeshm.github.io/cassandra/3.11.1/> ). The method is a bit
hacky as I noted in CASSANDRA-13907. A daily cronjobs updated the repo if
docs are updated. 3.9+ versions are available.




> Also, no offense to anyone at Sphinx but for a project our size it's not
> suitable.  We need to move off it now.  It's a problem.
>
> Can we go past this and on to the documenting!  Please help resolve this.
>
> How are we going to:
> Make the submission of code changes include required changes to
> documentation including the online documentation?
> Allow, encourage the online documentation to publish multiple versions of
> documentation concurrently including all officially supported versions?


Only on this point: we'll need to start by improving the website build
process. Michael's comment on 13907 (
https://issues.apache.org/jira/browse/CASSANDRA-13907?focusedCommentId=16211365=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-16211365
)
shows it's a painful, fiddly process. That seems to be the main blocker. I
think Jon has shown interest in moving to Hugo from the current Jekyll
setup.



> Move our project onto a more suitable program than Sphinx for our needs?
>
> Kenneth Brotman
>
> -Original Message-
> From: Eric Evans [mailto:john.eric.ev...@gmail.com]
> Sent: Thursday, March 15, 2018 7:50 AM
> To: dev@cassandra.apache.org
> Subject: Re: A JIRA proposing a seperate repository for the online
> documentation
>
> On Thu, Mar 15, 2018 at 4:58 AM, Rahul Singh <rahul.xavier.si...@gmail.com>
> wrote:
> >
> > I don’t understand why it’s so complicated. In tree docs are as good as
> any. All the old docs are there in the version control system.
> >
> > All we need to is a) generate docs for old versions b) improve user
> experience on the site by having it clearly laid out what is latest vs. old
> docs and c) have some semblance of a search maybe using something like
> Algolia or whatever.
>
> This.
>
> Keeping the docs in-tree is a huge win, because they can move in lock-step
> with changes occurring in that branch/version.  I don't think we've been
> enforcing this, but code-changes that alter documented behavior should be
> accompanied by corresponding changes to the documentation, or be rejected.
> Code-changes that correspond with undocumented behavior are an opportunity
> to include some docs (not grounds to reject a code-review IMO, but
> certainly an opportunity to politely ask/suggest).
>
> Publishing more than one version (as generated from the respective
> branches/tags), is a solvable problem.
>
> > > On Thu, Mar 15, 2018 at 1:22 Kenneth Brotman
> > > <kenbrot...@yahoo.com.invalid
> > > wrote:
> > >
> > > > https://issues.apache.org/jira/browse/CASSANDRA-14313
> > > >
> > > >
> > > >
> > > > For some reason I'm told by many committers that we should not
> > > > have sets of documentation for other versions than the current
> > > > version in a tree for that version. This has made it difficult,
> > > > maybe impossible to have documentation for all the supported
> > > > versions on the website at one time.
> > > >
> > > >
> > > >
> > > > As a solution I propose that we maintain the online documentation
> > > > in a separate repository that is managed as the current repository
> > > > under the guidance of the Apache Cassandr

RE: A JIRA proposing a seperate repository for the online documentation

[Kenneth Brotman]

Help me out here.  I could have had a website with support for more than one 
version done several different ways by now.  

A website with several versions of documentation is going to have 
sub-directories for each version of documentation obviously.  I've offered to 
create those sub-directories under the "doc" folder of the current repository; 
and I've offered to move the online documentation to a separate repository and 
have the sub-directories there.  Both were shot down.  Is there a third way?  
If so please just spill the beans.

Also, no offense to anyone at Sphinx but for a project our size it's not 
suitable.  We need to move off it now.  It's a problem.

Can we go past this and on to the documenting!  Please help resolve this.  

How are we going to:
Make the submission of code changes include required changes to documentation 
including the online documentation?
Allow, encourage the online documentation to publish multiple versions of 
documentation concurrently including all officially supported versions?
Move our project onto a more suitable program than Sphinx for our needs?

Kenneth Brotman

-Original Message-
From: Eric Evans [mailto:john.eric.ev...@gmail.com] 
Sent: Thursday, March 15, 2018 7:50 AM
To: dev@cassandra.apache.org
Subject: Re: A JIRA proposing a seperate repository for the online documentation

On Thu, Mar 15, 2018 at 4:58 AM, Rahul Singh <rahul.xavier.si...@gmail.com> 
wrote:
>
> I don’t understand why it’s so complicated. In tree docs are as good as any. 
> All the old docs are there in the version control system.
>
> All we need to is a) generate docs for old versions b) improve user 
> experience on the site by having it clearly laid out what is latest vs. old 
> docs and c) have some semblance of a search maybe using something like 
> Algolia or whatever.

This.

Keeping the docs in-tree is a huge win, because they can move in lock-step with 
changes occurring in that branch/version.  I don't think we've been enforcing 
this, but code-changes that alter documented behavior should be accompanied by 
corresponding changes to the documentation, or be rejected.  Code-changes that 
correspond with undocumented behavior are an opportunity to include some docs 
(not grounds to reject a code-review IMO, but certainly an opportunity to 
politely ask/suggest).

Publishing more than one version (as generated from the respective 
branches/tags), is a solvable problem.

> > On Thu, Mar 15, 2018 at 1:22 Kenneth Brotman 
> > <kenbrot...@yahoo.com.invalid
> > wrote:
> >
> > > https://issues.apache.org/jira/browse/CASSANDRA-14313
> > >
> > >
> > >
> > > For some reason I'm told by many committers that we should not 
> > > have sets of documentation for other versions than the current 
> > > version in a tree for that version. This has made it difficult, 
> > > maybe impossible to have documentation for all the supported 
> > > versions on the website at one time.
> > >
> > >
> > >
> > > As a solution I propose that we maintain the online documentation 
> > > in a separate repository that is managed as the current repository 
> > > under the guidance of the Apache Cassandra PMC (Project Management 
> > > Committee); and that in the new repository . . .
> > >
> > >
> > >
> > > Please see the jira. I hope it's a good answer to everyone.

--
Eric Evans
john.eric.ev...@gmail.com

-
To unsubscribe, e-mail: dev-unsubscr...@cassandra.apache.org
For additional commands, e-mail: dev-h...@cassandra.apache.org


-
To unsubscribe, e-mail: dev-unsubscr...@cassandra.apache.org
For additional commands, e-mail: dev-h...@cassandra.apache.org

Re: A JIRA proposing a seperate repository for the online documentation

[Eric Evans]

On Thu, Mar 15, 2018 at 4:58 AM, Rahul Singh
 wrote:
>
> I don’t understand why it’s so complicated. In tree docs are as good as any. 
> All the old docs are there in the version control system.
>
> All we need to is a) generate docs for old versions b) improve user 
> experience on the site by having it clearly laid out what is latest vs. old 
> docs. and c) have some semblance of a search maybe using something like 
> Algolia or whatever.

This.

Keeping the docs in-tree is a huge win, because they can move in
lock-step with changes occurring in that branch/version.  I don't
think we've been enforcing this, but code-changes that alter
documented behavior should be accompanied by corresponding changes to
the documentation, or be rejected.  Code-changes that correspond with
undocumented behavior are an opportunity to include some docs (not
grounds to reject a code-review IMO, but certainly an opportunity to
politely ask/suggest).

Publishing more than one version (as generated from the respective
branches/tags), is a solvable problem.

> > On Thu, Mar 15, 2018 at 1:22 Kenneth Brotman  > wrote:
> >
> > > https://issues.apache.org/jira/browse/CASSANDRA-14313
> > >
> > >
> > >
> > > For some reason I'm told by many committers that we should not have sets 
> > > of
> > > documentation for other versions than the current version in a tree for
> > > that
> > > version. This has made it difficult, maybe impossible to have
> > > documentation
> > > for all the supported versions on the website at one time.
> > >
> > >
> > >
> > > As a solution I propose that we maintain the online documentation in a
> > > separate repository that is managed as the current repository under the
> > > guidance of the Apache Cassandra PMC (Project Management Committee); and
> > > that in the new repository . . .
> > >
> > >
> > >
> > > Please see the jira. I hope it's a good answer to everyone.

-- 
Eric Evans
john.eric.ev...@gmail.com

-
To unsubscribe, e-mail: dev-unsubscr...@cassandra.apache.org
For additional commands, e-mail: dev-h...@cassandra.apache.org

Re: A JIRA proposing a seperate repository for the online documentation

[Rahul Singh]

I don’t understand why it’s so complicated. In tree docs are as good as any. 
All the old docs are there in the version control system.

All we need to is a) generate docs for old versions b) improve user experience 
on the site by having it clearly laid out what is latest vs. old docs. and c) 
have some semblance of a search maybe using something like Algolia or whatever.

--
Rahul Singh
rahul.si...@anant.us

Anant Corporation

On Mar 14, 2018, 7:58 PM -0400, Murukesh Mohanan , 
wrote:
> I think this was how it was in the dark ages, with the wiki and all. I
> believe the reason why they shifted to in-tree docs is that this way,
> people who make changes to the code are more likely to make the
> corresponding doc changes as well, and reviewers have it easier to ensure
> docs are updated with new patches. The wiki was often left behind the code.
> So I they will move back to an out-of-tree doc system again. The way
> Michael put it in CASSANDRA-13907, the main blocker behind having docs for
> multiple versions online is that it's a pain just to get the docs for trunk
> updated. Once the current site update process is improved, multiple
> versions can more easily be added.
>
>
> On Thu, Mar 15, 2018 at 1:22 Kenneth Brotman  wrote:
>
> > https://issues.apache.org/jira/browse/CASSANDRA-14313
> >
> >
> >
> > For some reason I'm told by many committers that we should not have sets of
> > documentation for other versions than the current version in a tree for
> > that
> > version. This has made it difficult, maybe impossible to have
> > documentation
> > for all the supported versions on the website at one time.
> >
> >
> >
> > As a solution I propose that we maintain the online documentation in a
> > separate repository that is managed as the current repository under the
> > guidance of the Apache Cassandra PMC (Project Management Committee); and
> > that in the new repository . . .
> >
> >
> >
> > Please see the jira. I hope it's a good answer to everyone.
> >
> >
> >
> > KennethBrotman
> >
> >
> >
> >
> >
> > --
>
> Murukesh Mohanan,
> Yahoo! Japan

Re: A JIRA proposing a seperate repository for the online documentation

[Murukesh Mohanan]

I think this was how it was in the dark ages, with the wiki and all. I
believe the reason why they shifted to in-tree docs is that this way,
people who make changes to the code are more likely to make the
corresponding doc changes as well, and reviewers have it easier to ensure
docs are updated with new patches. The wiki was often left behind the code.
So I they will move back to an out-of-tree doc system again. The way
Michael put it in CASSANDRA-13907, the main blocker behind having docs for
multiple versions online is that it's a pain just to get the docs for trunk
updated. Once the current site update process is improved, multiple
versions can more easily be added.


On Thu, Mar 15, 2018 at 1:22 Kenneth Brotman 
wrote:

> https://issues.apache.org/jira/browse/CASSANDRA-14313
>
>
>
> For some reason I'm told by many committers that we should not have sets of
> documentation for other versions than the current version in a tree for
> that
> version.  This has made it difficult, maybe impossible to have
> documentation
> for all the supported versions on the website at one time.
>
>
>
> As a solution I propose that we maintain the online documentation in a
> separate repository that is managed as the current repository under the
> guidance of the Apache Cassandra PMC (Project Management Committee); and
> that in the new repository . . .
>
>
>
> Please see the jira.  I hope it's a good answer to everyone.
>
>
>
> KennethBrotman
>
>
>
>
>
> --

Murukesh Mohanan,
Yahoo! Japan

A JIRA proposing a seperate repository for the online documentation

[Kenneth Brotman]

https://issues.apache.org/jira/browse/CASSANDRA-14313

 

For some reason I'm told by many committers that we should not have sets of
documentation for other versions than the current version in a tree for that
version.  This has made it difficult, maybe impossible to have documentation
for all the supported versions on the website at one time.  

 

As a solution I propose that we maintain the online documentation in a
separate repository that is managed as the current repository under the
guidance of the Apache Cassandra PMC (Project Management Committee); and
that in the new repository . . .

 

Please see the jira.  I hope it's a good answer to everyone.

 

KennethBrotman