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
