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 >
