+1 on the update on how to split documentation! Thanks Patrick for the proposal!
I am also not bought on the day 1/day 2 approach, and I usually enjoy more kind of quick and easy different “run these commands” kind of bits. Which brings me to a slightly different but (in my humble opinion topic). We still don’t have a “run this command to have the ecosystem ready” type of thing with something like a docker compose bringing up a whole ecosystem (including several nodes, sidecar, analytics support, CDC with Kafka…). That sounds like a really useful addition to documentation. Cheers! Bernardo El El dom, 5 abr 2026 a las 1:25, Josh McKenzie <[email protected]> escribió: > nit / quick observation: a bunch of front-end communities have "getting > started in N minutes" style on-ramps for people. It helps to know how much > time you need to commit to something to see results - to Samson's point, > "Day 1" and "Day 2" give the impression of a multi-day investment required > to ramp. > > I'd love to see us have a "Getting Started in 15 minutes" style landing > page for each persona w/easy on-ramps to get things stood up and running in > docker containers doing dev against a local cluster. > > I like the persona-based focus and the rest of the docs structure change > as well. Thanks for taking this on Patrick! > > On Sat, Apr 4, 2026, at 2:02 PM, mapyourown wrote: > > I commend you for taking the initiative to update the documentation, it’s > a critical part of any successful open-source project. > > Here are a few recommendations: > > 1. The operator and developer roles often overlap. It might be > beneficial to combine these sections and move the shared, more general > topics into a separate reference section for better clarity and reuse. > 2. I’m not fully aligned with the “Day 1” and “Day 2” structure in the > Getting Started guide. It can set an unnecessary expectation, whereas the > actual time required can vary significantly depending on a developer’s > experience and how things progress. > 3. How do we plan to reconcile this with the existing documentation on > the website? Should we retain the current layout and update the content > incrementally, or are we considering a more comprehensive restructure? It > would be helpful to clarify the path forward. > 4. Can we add maybe a release block, and add what new in every release > feature instead of what new in Cassandra 6. From the discussion new feature > and release are in the pipeline. And having that section help to organize > what released and how it affected who upgrade to that specific features. > > Wanted to share when I see the proposed documentation. > > Samson > > On Fri, Apr 3, 2026 at 4:28 PM Patrick McFadin <[email protected]> wrote: > > I want to propose we change how our docs are organized. > > Here is the current layout. You can navigate here: > https://cassandra.apache.org/doc/latest/ > Main > - Glossary > - How to report bugs > - Contact us > - Development > Cassandra > - FAQ > - Getting Started > - What’s new > - Architecture > - Data Modeling > - Cassandra Query Language (CQL) > - Vector Search overview > - Managing > - Troubleshooting > - Reference > - Plug-ins > > The new layout I'm proposing aligns our documents with the various > personas looking for in-depth treatment of whatever they need to do. The > format I'm going with is a noun-verb type format. "I'm an X, and I need to > do Y". Here is the layout II created to the first layer deep in the tree. > You can view it here and click deeper into the various sections: > https://pmcfadin.github.io/cassandra6-docs-workzone/home/draft/index.html > > Home > Operators > - Get Started > - Day 1: Deploy and Harden > - Day 2: Operate > - Upgrade > - Observe and Respond > - Backup and Recovery > - Automate > - Troubleshoot > - Tune > - Reference > Developers > - Get Started > - Learn > - Build > - Operate Your App > - CQL Reference > Contributors > - Orientation > - Architecture > - Codebase Internals > - SSTable Architecture > - Build and Test > - Feature Development > - Patches and Review > - Documentation > - Release and Publish > - Generated Docs > - Contribution Policy > Reference > - Configuration > - Nodetool > - Tools > - Native Protocol > - CQL Commands > - CQL Reference > - Version and Compatibility > - SAI Virtual Table Indexes > What’s New > - What’s New in Cassandra 6 > > It's a radical change in our layout, but it aligns with part of my talk at > the last CoC about how the Cassandra community is growing so large and how > we've formed sub-communities. Hopefully, it aligns with those communities > and makes it easier to find and add new information. Especially when the > organization prompts discussions like "You know what is missing in this > section?" > > Patrick > > >
