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
