RE: A JIRA proposing a seperate repository for the online documentation
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 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:
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 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
Re: A JIRA proposing a seperate repository for the online documentation
> > 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
RE: A JIRA proposing a seperate repository for the online documentation
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 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.htm > > l The resulting static HTML from Sphinx is hosted on ASF > > infrastructure. > > > > -
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 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 > > > > > > > - > 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, 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 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 > > - 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
> > 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
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
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 , 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 > , 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 re
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 , 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 > , 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" 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 o
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 , 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 > , 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" 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: Cassan
RE: A JIRA proposing a seperate repository for the online documentation
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 , 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" 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&qid=1521230539&sr=8-1&keywords=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.
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 , 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" 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&qid=1521230539&sr=8-1&keywords=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 > 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
RE: A JIRA proposing a seperate repository for the online documentation
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" 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&qid=1521230539&sr=8-1&keywords=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 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 wrote: >> >> On Fri, Mar 16, 2018 at 0:19 Kenneth Brotman >> 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 goi
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" 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&qid=1521230539&sr=8-1&keywords=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 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 wrote: >> >> On Fri, Mar 16, 2018 at 0:19 Kenneth Brotman >> 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. Not
RE: A JIRA proposing a seperate repository for the online documentation
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&qid=1521230539&sr=8-1&keywords=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 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 >> wrote: >> >> On Fri, Mar 16, 2018 at 0:19 Kenneth Brotman >> 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. &g
Re: A JIRA proposing a seperate repository for the online documentation
On Thu, Mar 15, 2018 at 11:40 AM, Kenneth Brotman 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 >> wrote: >> >> On Fri, Mar 16, 2018 at 0:19 Kenneth Brotman >> 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&page=com.atlassian.jira.plugin.system.issuetabpanels:comment >> -tabpanel#comment-16211365 >> <https://issues.apache.org/jira/browse/CASSANDRA-13907?focusedCommentI >> d=16211365&page=com.atlassian.jira.plugin.system.issuetabpanels:commen >> t-tabpanel#comment-16211365> >> ) >> shows it's a painful, fiddly process. That seems to
RE: A JIRA proposing a seperate repository for the online documentation
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 > wrote: > > On Fri, Mar 16, 2018 at 0:19 Kenneth Brotman > 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&page=com.atlassian.jira.plugin.system.issuetabpanels:comment > -tabpanel#comment-16211365 > <https://issues.apache.org/jira/browse/CASSANDRA-13907?focusedCommentI > d=16211365&page=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 >> >> wrote: >>> >>> I don’t understand why it’s so complicated. In tree docs are as good >>> as >> any. All the
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 > wrote: > > On Fri, Mar 16, 2018 at 0:19 Kenneth Brotman <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&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-16211365 > > <https://issues.apache.org/jira/browse/CASSANDRA-13907?focusedCommentId=16211365&page=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 >> 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 sho
Re: A JIRA proposing a seperate repository for the online documentation
On Fri, Mar 16, 2018 at 0:19 Kenneth Brotman 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&page=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 > 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 . . . > > > > > > &g
RE: A JIRA proposing a seperate repository for the online documentation
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 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 - 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
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
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
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