I’ve previously deep dived into Static Site generators and there are numerous ones.
http://leaves.anant.us/#!/leaf/7255?tag=static.site I don’t like changing technology for the sake of change. I think it’s a stupid waste of time. In one hand I agree, the substance is more important than the form. On the other hand. I [insert f-bomb] hate writing HTML / CSS, or restructured text. Markdown is much easier. Hugo is one of many that if setup right, it can save a ton of time and make it more accessible for people to contribute. There is a difference however in developer documentation for developers of cassandra, user documentation for cassandra users, documentation for and administrators. They are different users and have different use cases. Some need reference style docs, others need guides. Some good examples, (the software quality not-withstanding), correlate with software propularity are Wordpress. I am not wild about Wordpress, but their codex.wordpress.org has been generally a good “user doc.” Envision the outcome even if you have to mimic someone else. I don’t mind stealing/copying if it gets us one step further than we are. The reaper docs look easy to maintain and I could care less about Hugo, Hexo, Jekyll, Hyde, KafkasMom, EinsteinsDog, ShrodingersCat static site generator. I think action should come before decision in open source. Prove something before suggesting a change. Jon’s reaper example is good. If anyone has something better, show it. Prove it. -- Rahul Singh rahul.si...@anant.us Anant Corporation On Mar 16, 2018, 6:54 PM -0400, Kenneth Brotman <kenbrot...@yahoo.com.invalid>, wrote: > There is no need for another program. Keep the code in html, css and js. > People can modify that and show proposed changes in that. No need to convert > back and forth from other formats. If someone is doing something more > involved, they probably already have a program themselves. > > -----Original Message----- > From: beggles...@apple.com [mailto:beggles...@apple.com] > Sent: Friday, March 16, 2018 3:16 PM > To: dev@cassandra.apache.org > Subject: Re: A JIRA proposing a seperate repository for the online > documentation > > It would probably be more productive to list some specific concerns you have > with Hugo. Then explain why you think they make using it a bad idea. Then > offer some alternatives. > > On 3/16/18, 1:18 PM, "Kenneth Brotman" <kenbrot...@yahoo.com.INVALID> wrote: > > Thanks for that Eric Evans. > > I'm not sure Hugo is the way to go. I don't see how I would generate the > quality of work I would want with it. It seems like another example of coders > learning and using a more complicated program to generate the code they could > have already generated - it’s a disease in the I.T. industry right now. But I > could be wrong. > > Here's the thing. I've been spending a lot of my time for the past three > weeks now trying to help with the website. That is a tiny website. I've never > worked with a website that tiny. Bear with me. > > I'm studying Jeff Carpenter and Eben Hewitt's book: Cassandra The Definitive > Guide > https://www.amazon.com/Cassandra-Definitive-Guide-Distributed-Scale/dp/1491933666/ref=sr_1_1?ie=UTF8&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@yahoo.cominvalid> wrote: > > Well pickle my cucumbers Jon! It's good to know that you have experience > > with Hugo, see it as a good fit and that all has been well. I look forward > > to the jira epic! > > > > How exactly does the group make such a decision: Call for final discussion? > > Call for vote? Wait for the PMC to vote? > > Good question! > > Decisions like this are made by consensus; As 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?focusedCommentI > > > d > > > =16211365&page=com.atlassian.jira.plugin.system.issuetabpanels:commen > > > t > > > -tabpanel#comment-16211365 > > > <https://issues.apache.org/jira/browse/CASSANDRA-13907?focusedComment > > > I > > > d=16211365&page=com.atlassian.jira.plugin.system.issuetabpanels:comme > > > 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 >
