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