I don't want AI writing creative content, but what about docs?

This article was written without any AI assistance.

I love writing.

You'll find all sorts of things I've written online, from various types of technical content ([1] [2] [3]) to travel pieces and even poems.

I'd never consider using AI to write this content, because my writing's for me. My primary goal with writing is expressing myself -- be it to structure my thoughts, to explore topics in more depth, or to simply get things off my chest.

Like many others, I worry about AI-generated content flooding our timelines, suppressing all the beautifully imperfect creative pieces other writers put out into the world.

But as a developer who's often been frustrated by poor and outdated documentation out there, I found myself thinking: I don't want AI to write content for me, but what about docs?

Now, I believe some will take issue with the title of this article, arguing that documentation is also creative content.

And I'd actually agree with that statement.

Personally, I take great pride in writing docs, and have driven a culture of active documentation in every organization I've worked in.

It gives me joy to have someone ask me a question on Slack only for me to link them to a doc that answers that question and their follow-up, while also covering background context which might teach the reader something interesting (though it kinda annoys me if they didn't search for it in the first place).

But while I use writing as a way to think more clearly, lots of developers I've worked with or talked to struggle deeply with writing documentation.

It's not uncommon to hear things like:

• "I don't have time"
• "I'm not sure how to write about this"
• "Things are moving fast, any documentation will quickly get out of date"
• "Where do I even put this?"

As a result, you'll find many projects in the wild with bad or incomplete documentation, and even more internal tools with the same problems, with context living inside the brain of that one person who wrote that one service back in the day.

Some organizations help mitigate a bit of this paralysis (at least as it pertains to how to write) by providing extensive technical writing guidelines (like this really comprehensive RedHat doc), but at this point we're stripping out most of the creative writing portion anyway.

What's more, we're increasingly not even reading actual docs as much anymore. For me at least, my go-to for publicly-available tools is to ask an LLM my question first and direct my further digging from there. I still find myself ending up on official documentation often enough, but I suspect the frequency of this will decrease. I at least believe models are getting better after all.

You then have docs like this Kapa.ai piece "Writing documentation for AI: best practices" which is also great but it makes me think that at least as it pertains to docs, we're either directly writing for AI (if your company uses a tool like Kapa) or we're doing so indirectly, either because your docs will get scraped or because someone will eventually add them as context to an LLM.

So I believe there will still be space for creative technical writing, but as far as providing specs and helping people understand interfaces and systems, it's better that there is an updated doc (even if it's not written in the most authentic way) than there be nothing at all, or worse, that you run into misleading outdated information.

Auto-generated docs are not a new concept -- I mean, Swagger has been around for a some time now. And while API documentation is the perfect candidate for auto-generated stuff (since it usually follows a rigid structure) we're probably getting close to a point where more documentation can be updated or even generated automatically, both in the technical realm, but also at the intersection of tech and product, and maybe even further.

So that's what we're trying to do with Skald. We're building AI-powered tooling to encourage humans to write docs (by pointing out knowledge gaps and auto-generating cohesive docs from notes); help them write better docs (that follow style guidelines, avoid conflicts, etc); and automatically generate documentation (e.g. from code).

We're early on this journey, and we'd love to hear feedback and ideas.

If you have anything to say, email me at yakko [at] useskald [dot] com and let's have a chat!