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 > > 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 > > <kenbrotman@yahoocominvalid> 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?focusedCom > > > > me > > > > ntI > > > > d > > > > =16211365&page=com.atlassian.jira.plugin.system.issuetabpanels:c > > > > om > > > > men > > > > t > > > > -tabpanel#comment-16211365 > > > > <https://issues.apache.org/jira/browse/CASSANDRA-13907?focusedCo > > > > mm > > > > ent > > > > I > > > > d=16211365&page=com.atlassian.jira.plugin.system.issuetabpanels: > > > > co > > > > mme > > > > n > > > > 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 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 > > > > > > > > > > -- > > > > > > > > Murukesh Mohanan, > > > > Yahoo! Japan > > > > > > > > > > > > ------------------------------------------------------------------ > > > -- > > > - To unsubscribe, e-mail: dev-unsubscr...@cassandra.apache.org > > > For additional commands, e-mail: dev-h...@cassandra.apache.org > > > > > > > > > > > -- > > 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 > > > > > > > > > > > > -------------------------------------------------------------------- > > - 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 > > > > > --------------------------------------------------------------------- > 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
