**Scope** I'll start a discussion thread about the format change. Most of the pages were simply rearranged into the buckets, but large tracts of information were just missing, which, after trying to shoehorn things in, I realized the docs had a poor foundation. My solution to the overwhelming amount of things was to ask everyone to pick just one thing they cared about and review it.
**AI-generated content and community process** The information from there was drawn from those discussions and from other OSS projects where the same thing is happening. I expected this to be the hot button, and it's already happening, so we should settle this and get it in writing. Patrick On Thu, Apr 2, 2026 at 1:58 PM Mick <[email protected]> wrote: > Thanks for the work here, the docs clearly need attention and it's awesome > to see someone driving it! > > I want to raise two separate concerns. > > **Scope** > > Mixing new content additions with a wholesale restructure of the layout in > a single contribution makes it very hard to review, and hard to have a > traceable, community-owned conversation about *why* things are being done > in particular ways. I'd suggest splitting this into two parallel tracks: > > - New or updated content added as focused, reviewable PRs > - A separate discussion thread (here on the list) to propose and evaluate > layout/structural changes, inviting broader input before any restructure > lands > > That way the community can engage meaningfully with both, rather than > being presented with a fait accompli that's difficult to unpack. > > > **AI-generated content and community process** > > The content reads as AI-generated, and I want to flag that we have some > unfinished business here as a project. Ariel opened a thread in May on > exactly this topic: what vetting we require for AI-generated contributions; > and IIRC I'm not sure we reached a resolution/consensus. This seems like a > good tangible example to test it on. > > The ASF's guidance doesn't prohibit AI-generated contributions, but it > does ask that contributors address copyright provenance (which tool, > whether output was scanned or otherwise vetted for third-party material), > and recommends disclosing tooling in commit messages. You've made brief > mention of that here, but I think if we break the proposal up into smaller > incremental PRs, and work with providing the (specific) information around > the AI-generated content, it'll be easier to build the collaborative > momentum needed. > > > > > > On 2 Apr 2026, at 17:51, Patrick McFadin <[email protected]> wrote: > > > > Hello all my fellow Cassandra people. > > > > I have been working on a big rewrite of our Cassandra docs for a while. > The current version released with 5 is "Just the facts" on several things. > DataStax docs have filled in many gaps over the years, but a few > developments have made me rethink our docs. 1) Since Lorena retired, there > hasn't been the same focus on the in-tree docs. 2) Let's face it, LLMs have > made docs WAY easier to generate and maintain. If you can point to the > sweet spot for LLMs, generating docs is at the top of the list. > > > > Now I need everyone's help getting this in-tree. What I have done is set > up a temporary repo in my github as a workspace as I'm doing a lot of the > heavy lifting. Since this is generating HTML, it will be easy for everyone > to look and comment. Once I get to a good settling place, then I'll bring > it over to trunk and get it published on our website. > > > > The big changes: > > > > The primary change has been in how the docs are presented. Before the > docs were top-down and mostly reference. If you had a specific use case or > need, it was up to you to figure out where in the docs the data was > located. I've flipped that to be persona-based now. The 4 major buckets > I've put things in are Developer, Operator, Contributor, and Reference. For > example, Accord and ACID transactions have completely different focuses > when talking to a developer or an operator. Each person will find what's > relevant to them. > > > > In that, I added a lot more pages to each. The sources I took from were > previous docs, CEPs, the actual code, presentations, and blogs over the > years. I even used Jon Haddad's Cassandra agentic coding skills! (A huge > help for validation) > > > > What I need now is people looking at and judging the output. I'm > constantly reading and revising, but I need your input. The best thing I > could ask for is to pick one thing you are the most opinionated about. > Maybe it's UCS or repairs. A feature you worked on that isn't covered well. > You pick. The way I would like you to look at it is "Is this enough > information and I would share the link." If it needs more or is missing, > let me know. Let's fix it today. > > > > Here is the review link: > https://pmcfadin.github.io/cassandra6-docs-workzone/home/draft/index.html > > > > Some notes on navigation. You will see the different personas on the > left hand nav. When you click on one, it changes the view. That's just how > Antora works in this environment. In prod, it will be cleaner. To go back > to the top level, just click the home icon. > > > > To communicate changes, you can either reply to this thread or start a > convo in the #cassandra-comdev channel on ASF Slack. Or, you can private > message me on whatever platform you choose. > > > > Thanks and looking forward to some awesome docs in Cassandra 6! > > > > Patrick > >
