| I do have this: https://pmcfadin.github.io/cassandra6-docs-workzone/operators/draft/quickstart.html
Which is mostly docker based and gives you the quick win. Maybe surface this better? Patrick +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 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: - 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.
- 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.
- 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.
- 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
I want to propose we change how our docs are organized.
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
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?"
|
