Updated Docs: A Website Story

Our documentation website has been reorganized and expanded to include the features and functionalities we have added over the past 8-10 months, and beyond. The work was accomplished with the help of AI, including the writing, so I want to talk a bit about why it's important to me to be transparent about that.

Why I use AI to write

AI helps me keep the documentation site up to date. Highlighting the changes it makes helps me sleep at night.

I enjoy using AI tools when I write because I'm a slow writer and a habitually non-linear thinker. Without the help, a lot of what I have wanted to write has gone stale, stated the conclusion before the premise, and/or never seen the light of day. With the help, I'm able to produce (mostly) decent-quality drafts and get into a flow state more readily. But it comes with a cost: there's that much more content to review and edit! The bottleneck just moved from writing to reviewing. So in order to actually Get Things Done™, I either need to get real specific about what "done" means or I need to publish sooner, before everything is fully reviewed.

Herein lies the dilemma that has me Sweating Bullets™: passing off longform AI-generated text as human-made content is misleading. Especially if I'm knowingly publishing it early. That would feel actively dishonest. So what do? What can has do?

Main screen, turn on

If I know it's "going to take a while" to review and edit all the new content on our documentation website, I can at least be really loud about AI's involvement in the meantime. There are a couple of established ways of doing it (and some "less established" ways, which I mention at the end).

1. Semantic watermarking works by subtly altering word choices in a body of text to create a hidden signature that can be detected by a trained model. Watermarking is good at identifying which model generated all or sections of a piece of text.
2. The Coalition for Content Provenance and Authenticity (C2PA) is both a mouthful and a standard for embedding a verifiable chain of custody in media. C2PA is good for establishing the origin and authenticity of a finished piece of art.

Neither shows a reader which words AI wrote, and neither is meant to be used during the writing process, so I came up with a quick way to show AI's involvement down to each character. It's like a local feedback system. I can see what changes an LLM agent made and keep track of those changes over time without using any special tools (even copy and paste works). At the end of the process, I can highlight those markings to draw attention to the parts where AI was involved.

For readers, it helps avoid the Slop or Not™ guessing game, but it is not perfect.

• I can type things I remembered from an AI earlier, or an AI can repeat something it was fed in a prompt or other context. But highlighting works well in the sloppiest of cases, like saying, "It's okay, it's not you. This really is awful, sloppy crap."
• It doesn't work on text written previously.
• Crucially: it is not a trust signal. Keeping track of which characters came from where is not historical proof. It's a disclosure: my claim about how this was written.

Why it matters

When all writing was human writing, even the crappy stuff depended on some amount of human energy.

It's important for readers to know how the content sausage was made and decide for themselves how much stock to put in it. Kind of like qualitative food labeling. It's low in sugar. It's high in AI edits.

Up until 2022, it was safe to assume that longform content was produced by a real human person. We didn't give it a second thought. Machine-made text was templated, on the order of a few phrases or sentences, and for the most part was given away by the repetition. Fast-forward to today: past a certain level of quality, it's not so easy to tell the difference between human and AI-produced text (once the obvious tells are removed).

What changed is the energy differential. The imbalance between how little time a draft can take to generate and how much attention it still asks of a reader. Even a small deficit can add up over time. As we well know from another kind of public deficit. Disclosure lets readers decide where to spend their attention.

Some novel approaches

I mentioned at the top that there are other ways to show AI's involvement in content. Here are a few:

• Reference content that no AI ever would. Like a version of Almost Honest by Megadeth, live at Woodstock 1999.
• Make multiple references to the same band without explanation.
• Show your working copies (or git commits, or a changelog, or a diff of the text). A maximalist might choose to include the full conversation history.
• Use a CRDT document format, like Yjs or Automerge, to track each person and AI as a separate voice (kind of like how Google Docs works).
• Record it live like Paul Graham's Startups in 13 Sentences experiment.

Where to go from here

I'm going to keep working on this approach (which I'm calling TextProv for now). It's already live on the docs site, where you can turn on "Highlight AI edits" in the sidebar to see it working. We'll see how it goes there. I'm going to try it with new blog posts as well. Writing blog posts is very different from writing product documentation, so my hunch is that the highlights will be pretty sparse here. Plus it's not really de rigueur to rewrite a post after the fact (like I'm doing with the documentation), but that might be something to focus TextProv on in the future.