Re: Proof of concept for Cassandra docs conversion
I agree as well. Nice work, Lorina! This POC is a really good start. It has a bit more of a modern feel to it. The navigation bar on the side makes the information very accessible. This is a must for technical documentation. Would it be possible to have a search bar somewhere on the site? I think this would be useful to allow a user to navigate quickly to something they know they are after e.g. a nodetool command or configuration setting. Kind regards, On Fri, 12 Jun 2020 at 02:02, Jon Haddad wrote: > Agreed. This is an awesome POC in a pretty short period of time. > > I suspect with a little polish and cleanup this will be an improvement over > the existing site in every way. > > Thanks for putting this together, Lorina! > > On Thu, Jun 11, 2020 at 7:36 AM Joshua McKenzie > wrote: > > > Left bar navigation and content navigation on top right are both > > aesthetically and usability-wise quite superior IMO (comparing to > > https://cassandra.apache.org/doc/latest/getting_started/configuring.html > ). > > > > I'm a fan. > > > > On Wed, Jun 10, 2020 at 2:21 PM Lorina Poland > wrote: > > > > > Hello all! > > > > > > Based on an earlier discussion about moving the OSS C* docs to > > > asciidoc, to allow more flexibility in maintaining the docs, I've done > > > a proof of concept about what it would take to accomplish a > > > conversion. I converted rSt files to asciidoc files using pandoc, did > > > some additional editing, and use antora (antora.org) as a static site > > > generator to build the docs. The result is here: > > > > > > > > > https://polandll.github.io/site/ASCIIDOC_POC/4.0/cassandra/getting_started/configuring.html#changing-the-location-of-directoriesThe > > > editing of the docs is NOT complete, but I completed enough to feel > > > confident that this process can be accomplished. Some YAML > > > configuration for antora was required, and I did a minimum of UI > > > configuration (added color banner, logo). Looking for feedback and > > > questions anyone may have. > > > > > > Thanks, > > > > > > Lorina Poland (DataStax tech writer) > > > > > >
Re: Proof of concept for Cassandra docs conversion
Thanks for the feedback, Murukesh! As I mentioned, the editing to fix all the formatting is not completed, but I wanted to share the work so far to get feedback. I have not tailored most of the styling of the website. I literally used the default antora UI, only changing the banner to green and adding the Cassandra logo. So all the navigation can use some additional work; in fact, I only created the navigation files for 2-3 of the sections. Same with the breadcrumbs, more work to make it production-worthy. (But aren't those breadcrumbs cool?!) I have tried a few different conversions. I believe I did try rSt-> HTML -> asciidoc, but I'll check my files again. I have 4 separate sources of files used to create this POC, some local on my Macbook, and some publicly available: So, right now, the pieces of the process are in 4 locations: 1. docs-site (local - where I run antora) 2. a clone of https://gitlab.com/antora/antora-ui-default (local - where I made minimal look and feel changes) 3. https://github.com/polandll/cassandra-examples/tree/master/rst-to-asciidoc-tests/ASCIIDOC (where I am storing the asciidoc files that I’ve converted/editing) 4. https://github.com/polandll/polandll.github.io (where the prototype docs website is located) Feel free to check out the *.adoc files in the 3rd resource, but know that I am actively making changes there. Thanks, Lorina On Thu, Jun 11, 2020 at 8:15 AM Murukesh Mohanan wrote: > Is the AsciiDoc source also on GitHub? > > Some things that I noticed: > > - The FAQ sidebar navigation is great! The TOC list at the top isn't > needed at all now. > - In the breadcrumb trail (e.g., ASCIIDOC_POC > Cassandra > FAQ, or > ASCIIDOC_POC > Cassandra Documentation > Glossary), *Cassandra* in the > Cassandra pages isn't a link but Cassandra Documentation is. > - Some of the code blocks are off (e.g, > > https://urldefense.proofpoint.com/v2/url?u=https-3A__polandll.github.io_site_ASCIIDOC-5FPOC_4.0_cassandra_cql_indexes.html-23create-2Dindex-2Dstatement=DwIBaQ=adz96Xi0w1RHqtPMowiL2g=bL2UpIjL4Mm1mCbqWThJUiPD-CmTXMALsIT2Ta-KfGk=8C0qNdZj2XHZ-aA4ZjwgWI_Y6Nael_kjR7Wp-6CiOLU=Eg_JbhzOrbE1c5RgXi1UHjOQ-Np-uTmzDyPukPwWvfE= > , > > https://urldefense.proofpoint.com/v2/url?u=https-3A__polandll.github.io_site_ASCIIDOC-5FPOC_4.0_cassandra_cql_mvs.html=DwIBaQ=adz96Xi0w1RHqtPMowiL2g=bL2UpIjL4Mm1mCbqWThJUiPD-CmTXMALsIT2Ta-KfGk=8C0qNdZj2XHZ-aA4ZjwgWI_Y6Nael_kjR7Wp-6CiOLU=emL2s3ZZkCU5-L2Zg0-mlYKamtcCh2NkqVSu5Wn41Ss= > ) > - Pandoc clobbered the "MV select" part in > > https://urldefense.proofpoint.com/v2/url?u=https-3A__polandll.github.io_site_ASCIIDOC-5FPOC_4.0_cassandra_cql_mvs.html=DwIBaQ=adz96Xi0w1RHqtPMowiL2g=bL2UpIjL4Mm1mCbqWThJUiPD-CmTXMALsIT2Ta-KfGk=8C0qNdZj2XHZ-aA4ZjwgWI_Y6Nael_kjR7Wp-6CiOLU=emL2s3ZZkCU5-L2Zg0-mlYKamtcCh2NkqVSu5Wn41Ss= > into the preceding note. > > I wonder if it will be worth it to try rSt -> HTML (using the current build > tools) -> AsciiDoc (using Pandoc). > > Yours, > Murukesh Mohanan > > > On Thu, 11 Jun 2020 at 03:21, Lorina Poland wrote: > > > Hello all! > > > > Based on an earlier discussion about moving the OSS C* docs to > > asciidoc, to allow more flexibility in maintaining the docs, I've done > > a proof of concept about what it would take to accomplish a > > conversion. I converted rSt files to asciidoc files using pandoc, did > > some additional editing, and use antora (antora.org) as a static site > > generator to build the docs. The result is here: > > > > > https://urldefense.proofpoint.com/v2/url?u=https-3A__polandll.github.io_site_ASCIIDOC-5FPOC_4.0_cassandra_getting-5Fstarted_configuring.html-23changing-2Dthe-2Dlocation-2Dof-2DdirectoriesThe=DwIBaQ=adz96Xi0w1RHqtPMowiL2g=bL2UpIjL4Mm1mCbqWThJUiPD-CmTXMALsIT2Ta-KfGk=8C0qNdZj2XHZ-aA4ZjwgWI_Y6Nael_kjR7Wp-6CiOLU=a_fQx4FtvGnSkExAfzZM2BZAiaOmEeo9EA8DXjAYKz4= > > editing of the docs is NOT complete, but I completed enough to feel > > confident that this process can be accomplished. Some YAML > > configuration for antora was required, and I did a minimum of UI > > configuration (added color banner, logo). Looking for feedback and > > questions anyone may have. > > > > Thanks, > > > > Lorina Poland (DataStax tech writer) > > >
Re: Proof of concept for Cassandra docs conversion
Just a note, to emphasize - I did not complete the conversion of all the files from rSt to asciidoc yet. I wanted feedback that this direction seemed acceptable to everyone. Sylvain, I'll check out the tool you mention and see if it provides better translation. A one-time conversion effort is just that, though; rSt has some decided quirks that make the conversion to any other markup challenging. Thanks for the feedback! Lorina On Thu, Jun 11, 2020 at 8:13 AM Sylvain Lebresne wrote: > Agreed the navigation is nicer. > > The content rst conversion is however far from perfect, especially in the > CQL parts. The grammar parts are all broken, most tables are really weird > (example: > > https://urldefense.proofpoint.com/v2/url?u=https-3A__polandll.github.io_site_ASCIIDOC-5FPOC_4.0_cassandra_cql_types.html=DwIBaQ=adz96Xi0w1RHqtPMowiL2g=bL2UpIjL4Mm1mCbqWThJUiPD-CmTXMALsIT2Ta-KfGk=HsSPj9vYYbc2vVPNFrAqnMLZAz2ViLNZhPvU3cP1dCc=v5p3jTSLjuG_8QlzsBv2bqNKV0OM7v2vrVfN85YAduc= > ) > and we lost almost all linking in those parts. > > I think that's up to pandoc not handling rst too well, and while that could > be fixed manually, it's going to be some work. So I'd suggest giving a shot > at > https://urldefense.proofpoint.com/v2/url?u=https-3A__pypi.org_project_sphinx-2Dasciidoc_=DwIBaQ=adz96Xi0w1RHqtPMowiL2g=bL2UpIjL4Mm1mCbqWThJUiPD-CmTXMALsIT2Ta-KfGk=HsSPj9vYYbc2vVPNFrAqnMLZAz2ViLNZhPvU3cP1dCc=Sk4bb6rmPcdu_CsF426Ta-p5mwkcJirmv5hsNf2FZxo= > as an alternative. I haven't > tested it, but it supposedly exists to be a better converter than pandoc > and it may save some of that manual work. > -- > Sylvain > > > On Thu, Jun 11, 2020 at 4:45 PM Ekaterina Dimitrova > > wrote: > > > I told the same to Lorina in person, +1 more fan > > > > On Thu, 11 Jun 2020 at 10:36, Joshua McKenzie > > wrote: > > > > > Left bar navigation and content navigation on top right are both > > > aesthetically and usability-wise quite superior IMO (comparing to > > > > https://cassandra.apache.org/doc/latest/getting_started/configuring.html > > ). > > > > > > I'm a fan. > > > > > > On Wed, Jun 10, 2020 at 2:21 PM Lorina Poland > > wrote: > > > > > > > Hello all! > > > > > > > > Based on an earlier discussion about moving the OSS C* docs to > > > > asciidoc, to allow more flexibility in maintaining the docs, I've > done > > > > a proof of concept about what it would take to accomplish a > > > > conversion. I converted rSt files to asciidoc files using pandoc, did > > > > some additional editing, and use antora (antora.org) as a static > site > > > > generator to build the docs. The result is here: > > > > > > > > > > > > > > https://urldefense.proofpoint.com/v2/url?u=https-3A__polandll.github.io_site_ASCIIDOC-5FPOC_4.0_cassandra_getting-5Fstarted_configuring.html-23changing-2Dthe-2Dlocation-2Dof-2DdirectoriesThe=DwIBaQ=adz96Xi0w1RHqtPMowiL2g=bL2UpIjL4Mm1mCbqWThJUiPD-CmTXMALsIT2Ta-KfGk=HsSPj9vYYbc2vVPNFrAqnMLZAz2ViLNZhPvU3cP1dCc=wrHgAx24wI9dskwFiDgg8jtb__tc9HLjRDaCeerk7XE= > > > > editing of the docs is NOT complete, but I completed enough to feel > > > > confident that this process can be accomplished. Some YAML > > > > configuration for antora was required, and I did a minimum of UI > > > > configuration (added color banner, logo). Looking for feedback and > > > > questions anyone may have. > > > > > > > > Thanks, > > > > > > > > Lorina Poland (DataStax tech writer) > > > > > > > > > >
Re: [DISCUSS] governance on the Apache Cassandra project
Thanks for the insight Jun. It's great to hear that a process that's erring on the side of flexibility, freedom, and under-prescription holds up well in practice! Have you folks run into any trouble w/lack of alignment (false negatives or positives) on what qualifies as major? > >- Any major new feature, subsystem, or piece of functionality > > On Thu, Jun 11, 2020 at 2:42 PM Jun Rao wrote: > Hi, everyone, > > Just want to briefly share our experience in Apache Kafka. This may or may > not apply to the Cassandra community. > > We started the KIP ( > > https://cwiki.apache.org/confluence/display/KAFKA/Kafka+Improvement+Proposals > ) > process in 2015. The following is the summary of the process. > > 1. It's designed for major new features or changes to public interfaces. > 2. Anyone can start a KIP as long as that person has the intention to carry > it through. > 3. The KIP first goes through a discussion phase and then a voting phase. > The vote requires +1 from at least 3 committers to pass. > > Overall, I think our experience with KIP is positive. It (a) made our > compatibility story much better since more people are paying attention to > public interface changes; (2) allowed major features to be discussed more > thoroughly and often made the original proposal better; (3) non-relevant > KIPs (e.g. covered by existing features or other KIPs) were mostly vetted > out in the early discussion phase. > > We made some minor adjustments along the way. For example, if minor changes > are later discovered during the implementation of an accepted KIP, those > changes can just be added to the voting thread. If there are no objections, > those changes are accepted without the need of a new vote. > > Sometimes, it does feel that KIP adds a bit overhead. For example, changing > a simple configuration requires the same multi-day process. However, that's > probably minor given the overall benefits. > > Thanks, > > Jun >
Re: [DISCUSS] governance on the Apache Cassandra project
Hi, everyone, Just want to briefly share our experience in Apache Kafka. This may or may not apply to the Cassandra community. We started the KIP ( https://cwiki.apache.org/confluence/display/KAFKA/Kafka+Improvement+Proposals) process in 2015. The following is the summary of the process. 1. It's designed for major new features or changes to public interfaces. 2. Anyone can start a KIP as long as that person has the intention to carry it through. 3. The KIP first goes through a discussion phase and then a voting phase. The vote requires +1 from at least 3 committers to pass. Overall, I think our experience with KIP is positive. It (a) made our compatibility story much better since more people are paying attention to public interface changes; (2) allowed major features to be discussed more thoroughly and often made the original proposal better; (3) non-relevant KIPs (e.g. covered by existing features or other KIPs) were mostly vetted out in the early discussion phase. We made some minor adjustments along the way. For example, if minor changes are later discovered during the implementation of an accepted KIP, those changes can just be added to the voting thread. If there are no objections, those changes are accepted without the need of a new vote. Sometimes, it does feel that KIP adds a bit overhead. For example, changing a simple configuration requires the same multi-day process. However, that's probably minor given the overall benefits. Thanks, Jun
Re: Proof of concept for Cassandra docs conversion
Agreed. This is an awesome POC in a pretty short period of time. I suspect with a little polish and cleanup this will be an improvement over the existing site in every way. Thanks for putting this together, Lorina! On Thu, Jun 11, 2020 at 7:36 AM Joshua McKenzie wrote: > Left bar navigation and content navigation on top right are both > aesthetically and usability-wise quite superior IMO (comparing to > https://cassandra.apache.org/doc/latest/getting_started/configuring.html). > > I'm a fan. > > On Wed, Jun 10, 2020 at 2:21 PM Lorina Poland wrote: > > > Hello all! > > > > Based on an earlier discussion about moving the OSS C* docs to > > asciidoc, to allow more flexibility in maintaining the docs, I've done > > a proof of concept about what it would take to accomplish a > > conversion. I converted rSt files to asciidoc files using pandoc, did > > some additional editing, and use antora (antora.org) as a static site > > generator to build the docs. The result is here: > > > > > https://polandll.github.io/site/ASCIIDOC_POC/4.0/cassandra/getting_started/configuring.html#changing-the-location-of-directoriesThe > > editing of the docs is NOT complete, but I completed enough to feel > > confident that this process can be accomplished. Some YAML > > configuration for antora was required, and I did a minimum of UI > > configuration (added color banner, logo). Looking for feedback and > > questions anyone may have. > > > > Thanks, > > > > Lorina Poland (DataStax tech writer) > > >
Re: Proof of concept for Cassandra docs conversion
Is the AsciiDoc source also on GitHub? Some things that I noticed: - The FAQ sidebar navigation is great! The TOC list at the top isn't needed at all now. - In the breadcrumb trail (e.g., ASCIIDOC_POC > Cassandra > FAQ, or ASCIIDOC_POC > Cassandra Documentation > Glossary), *Cassandra* in the Cassandra pages isn't a link but Cassandra Documentation is. - Some of the code blocks are off (e.g, https://polandll.github.io/site/ASCIIDOC_POC/4.0/cassandra/cql/indexes.html#create-index-statement, https://polandll.github.io/site/ASCIIDOC_POC/4.0/cassandra/cql/mvs.html) - Pandoc clobbered the "MV select" part in https://polandll.github.io/site/ASCIIDOC_POC/4.0/cassandra/cql/mvs.html into the preceding note. I wonder if it will be worth it to try rSt -> HTML (using the current build tools) -> AsciiDoc (using Pandoc). Yours, Murukesh Mohanan On Thu, 11 Jun 2020 at 03:21, Lorina Poland wrote: > Hello all! > > Based on an earlier discussion about moving the OSS C* docs to > asciidoc, to allow more flexibility in maintaining the docs, I've done > a proof of concept about what it would take to accomplish a > conversion. I converted rSt files to asciidoc files using pandoc, did > some additional editing, and use antora (antora.org) as a static site > generator to build the docs. The result is here: > > https://polandll.github.io/site/ASCIIDOC_POC/4.0/cassandra/getting_started/configuring.html#changing-the-location-of-directoriesThe > editing of the docs is NOT complete, but I completed enough to feel > confident that this process can be accomplished. Some YAML > configuration for antora was required, and I did a minimum of UI > configuration (added color banner, logo). Looking for feedback and > questions anyone may have. > > Thanks, > > Lorina Poland (DataStax tech writer) >
Re: Proof of concept for Cassandra docs conversion
Agreed the navigation is nicer. The content rst conversion is however far from perfect, especially in the CQL parts. The grammar parts are all broken, most tables are really weird (example: https://polandll.github.io/site/ASCIIDOC_POC/4.0/cassandra/cql/types.html) and we lost almost all linking in those parts. I think that's up to pandoc not handling rst too well, and while that could be fixed manually, it's going to be some work. So I'd suggest giving a shot at https://pypi.org/project/sphinx-asciidoc/ as an alternative. I haven't tested it, but it supposedly exists to be a better converter than pandoc and it may save some of that manual work. -- Sylvain On Thu, Jun 11, 2020 at 4:45 PM Ekaterina Dimitrova wrote: > I told the same to Lorina in person, +1 more fan > > On Thu, 11 Jun 2020 at 10:36, Joshua McKenzie > wrote: > > > Left bar navigation and content navigation on top right are both > > aesthetically and usability-wise quite superior IMO (comparing to > > https://cassandra.apache.org/doc/latest/getting_started/configuring.html > ). > > > > I'm a fan. > > > > On Wed, Jun 10, 2020 at 2:21 PM Lorina Poland > wrote: > > > > > Hello all! > > > > > > Based on an earlier discussion about moving the OSS C* docs to > > > asciidoc, to allow more flexibility in maintaining the docs, I've done > > > a proof of concept about what it would take to accomplish a > > > conversion. I converted rSt files to asciidoc files using pandoc, did > > > some additional editing, and use antora (antora.org) as a static site > > > generator to build the docs. The result is here: > > > > > > > > > https://polandll.github.io/site/ASCIIDOC_POC/4.0/cassandra/getting_started/configuring.html#changing-the-location-of-directoriesThe > > > editing of the docs is NOT complete, but I completed enough to feel > > > confident that this process can be accomplished. Some YAML > > > configuration for antora was required, and I did a minimum of UI > > > configuration (added color banner, logo). Looking for feedback and > > > questions anyone may have. > > > > > > Thanks, > > > > > > Lorina Poland (DataStax tech writer) > > > > > >
Re: Proof of concept for Cassandra docs conversion
I told the same to Lorina in person, +1 more fan On Thu, 11 Jun 2020 at 10:36, Joshua McKenzie wrote: > Left bar navigation and content navigation on top right are both > aesthetically and usability-wise quite superior IMO (comparing to > https://cassandra.apache.org/doc/latest/getting_started/configuring.html). > > I'm a fan. > > On Wed, Jun 10, 2020 at 2:21 PM Lorina Poland wrote: > > > Hello all! > > > > Based on an earlier discussion about moving the OSS C* docs to > > asciidoc, to allow more flexibility in maintaining the docs, I've done > > a proof of concept about what it would take to accomplish a > > conversion. I converted rSt files to asciidoc files using pandoc, did > > some additional editing, and use antora (antora.org) as a static site > > generator to build the docs. The result is here: > > > > > https://polandll.github.io/site/ASCIIDOC_POC/4.0/cassandra/getting_started/configuring.html#changing-the-location-of-directoriesThe > > editing of the docs is NOT complete, but I completed enough to feel > > confident that this process can be accomplished. Some YAML > > configuration for antora was required, and I did a minimum of UI > > configuration (added color banner, logo). Looking for feedback and > > questions anyone may have. > > > > Thanks, > > > > Lorina Poland (DataStax tech writer) > > >
Re: [DISCUSS] governance on the Apache Cassandra project
Integrated some feedback I got from Jon (good points both). Anyone else? On Wed, Jun 10, 2020 at 2:53 PM Joshua McKenzie wrote: > Thanks for that insight Pavel. Will be a helpful and useful reference as > we start to test out our CEP process after 4.0 solidifies. One thing that > really stood out to me worth calling out: >> >> >> >>- Engage the wider Swift community in the ongoing evolution of Swift, >>and >> >> >>- Maintain the vision and conceptual coherence of Swift. >> >> There is a natural tension between these two goals. Open evolution >> processes are, by nature, chaotic. Yet, maintaining a coherent vision for >> something as complicated as a programming language requires some level of >> coordination. The Swift evolution process aims to strike a balance that >> best serves the Swift community as a whole. > > > I'd love us to follow up on that topic (future vision, coherence, etc) on > the project after we iron out our voting and governance process. > > So that being said - there's no further feedback on the doc in its current > form. Anybody else have any thoughts on where things stand? > > > On Wed, Jun 10, 2020 at 1:55 PM Pavel Yaskevich wrote: > >> On Mon, Jun 8, 2020 at 3:12 AM Mick Semb Wever wrote: >> >> > > > With regards to CEPs, I personally don't see any value in voting to >> > start >> > > one. >> > > >> > > Agree with this, and I'd go even further - requiring a vote in order >> to >> > > propose an idea runs so counter to the idea of a CEP that it would >> > default >> > > the purpose of even having them. The CEP is the _proposal_ for a >> change >> > > that gets fleshed out enough so people can understand the idea and >> _then_ >> > > vote on it, not the other way around. >> > >> > >> > Totally agree that CEPs should be as light-weight as possible, and with >> the >> > sentiments above. But would also like to keep the discussion open to >> > encourage and include as many voices as possible. >> > >> > My _questioning_ is around the value in "initial exposure and >> discussion". >> > It is implied already that there is lazy consensus in starting a CEP, >> and >> > that starting a CEP is more than just an initial proposal of an idea. >> One >> > example is we require a CEP to have a Shepherd that is a PMC member. >> > Encouraging a vote, or better-yet keeping it light-weight: an initial >> > DISCUSS thread as early as possible in the CEP lifecycle does come with >> > value. From openly calling out for a Shepherd, to allowing the more >> > experienced community members to add their insight (without having to >> get >> > formally involved in it), there's potential value in encouraging such >> > open-mode opening discussion early on (versus the cost of additional >> > process). >> > >> > Really interested in hearing from folk from other communities and >> projects >> > that do CEP/CIP and how their lifecycle through the process works and >> what >> > they have learnt. >> > >> >> Here is a description of the process Swift Programming Language uses - >> https://github.com/apple/swift-evolution/blob/master/process.md. >> >
Re: Proof of concept for Cassandra docs conversion
Left bar navigation and content navigation on top right are both aesthetically and usability-wise quite superior IMO (comparing to https://cassandra.apache.org/doc/latest/getting_started/configuring.html). I'm a fan. On Wed, Jun 10, 2020 at 2:21 PM Lorina Poland wrote: > Hello all! > > Based on an earlier discussion about moving the OSS C* docs to > asciidoc, to allow more flexibility in maintaining the docs, I've done > a proof of concept about what it would take to accomplish a > conversion. I converted rSt files to asciidoc files using pandoc, did > some additional editing, and use antora (antora.org) as a static site > generator to build the docs. The result is here: > > https://polandll.github.io/site/ASCIIDOC_POC/4.0/cassandra/getting_started/configuring.html#changing-the-location-of-directoriesThe > editing of the docs is NOT complete, but I completed enough to feel > confident that this process can be accomplished. Some YAML > configuration for antora was required, and I did a minimum of UI > configuration (added color banner, logo). Looking for feedback and > questions anyone may have. > > Thanks, > > Lorina Poland (DataStax tech writer) >
