An undocumented feature does not exist

I’m writing those lines not long after Snowflake announced they fired 70 technical writing people over the excuse that AI can do their job.

As I reacted on LinkedIn:

Definitely one of the worst ideas possible. AI must be fed with solid context to produce adequate answers. Only humans can produce that context. And documentation is precisely that.

This triggered me to write about a best practice throughout teams I worked with, at Traveldoo, SensioLabs, Blackfire, Upsun and Bump.sh, coined in a simple way: an undocumented feature doesn’t exist.

Documentation as a user reference

There’s a fair chance that amongst the readers of this post, most are familiar with the RTFM acronym.

Let me spell it out for you:

• Read
• The
• You know, that word that starts with an F, and ends with ucking
• Manual

How can you ever spit this out to the face of a user in your best passive aggressive manner, if the effing manual doesn’t exist?

Out of introspection, do you believe that each and every of your features is self-discoverable? Meaning, that anyone in the world (even if reduced to your user base) will have the same brain stream as you while browsing through your app?

Let’s face it: even the biggest SaaS names in the world don’t offer the same UX for similar features. Have you ever tried to fetch your latest SaaS subscription invoice? Almost as hard as figuring out how a microwave oven with more than a single button works.

Documentation is like a map. When you’re lost, there is one place that describes precisely what you can do, and how you can do it. And when that piece of documentation is well written, you might even have a description of “why is that feature even interesting”.

If your user can’t find a given feature, or understand how to use it, no matter how much effort your designer put into it, it’s just like if it doesn’t exist.

Documentation as marketing

Do you know one of the key strengths of Symfony, the PHP Open Source project? Spoiler: documentation. And that is the case since its very early days.

Strong and thorough documentation, in the SaaS world, and even more in the dev tools world, is key to adoption. And it is key to acquisition as well, whether for basic considerations such as SEO, or higher level ones such as positioning. The cleaner, deeper and better discoverable docs, the more professional the product.

Documentation as food for AI

Working at Bump.sh, an API documentation platform brought my perception of documentation to a whole new level.

It’s been more than a year that we’re talking about MCP. Even though it is yet imperfect, the whole point of MCP is to let AI agents directly interact with APIs, based on their completed technical description. Otherwise called “documentation”.

It’s also been more than a year that a wide variety of tools, such as Kapa.ai, build support agents and features that feed on documentation to provide that natural language interface for helping users out.

Now in the API space, there is a key strategic asset: specifications, such as OpenAPI. Even though the practices in writing such documentation vary (some still generate it from code, while the best practices show the golden way is to write it before the code), they exist for a single purpose: provide the exact description of how an API is built and how humans and machines can interact with it. To the point where many see it as a contract, a signed agreement between parties on how they should interact at the programmatic level.

It brings structure, and it brings semantics. Together with depth and completeness, this is the most solid foundation you can give to an AI. And by the way, since we’re talking about AI generating docs, in that space it’s been a practice for years to generate OpenAPI files from code scripts (no AI needed since it is completely deterministic). Works fine with a couple of endpoints and verbs. It’s horrible as soon as the API complexity grows, and very soon completely useless.

Actually, it’s been a while that I regret there is no such standard for the rest of product docs. Should it be a combination of knowledge graphs, consensus on user interaction models and feature types, supported by a proper description language? Possibly the reason why it’s so complex to build, and why it doesn’t exist. Yet the entire market would have a lot to earn from this.

Product documentation method

An approach that doesn’t fix it all, but that I can still recommend: Diataxis.

It makes a clear separation between content that helps people learn and those that help people do, empower people to discover and empower the product to build adoption.

Following this approach helps you build:

• Tutorials
• How-to guides
• Explanation
• Reference doc

Product delivery and documentation

Let me put some agility into the story. Ever heard of the “Definition of Done”? No need to be a Scrum extremist. This is plain pragmatism. It is about having a checklist to determine whether your feature is ready to be shipped to production.

Yes, docs should be on that checklist. Yes, I mean both the internal docs that only the product devs read AND the user docs.

And in our world, it should even be part of the code that is pushed to test and staging environments, since as soon as you’ll use an agent to perform any pre-production tasks, that documentation will give it critical context.

WTFM

I’ve recently seen a post on LinkedIn from an interpreter explaining how their work will always be key, despite AI, through a specific example: the translation of Harry Potter names. It’s not just about having something that enables decent dubbing for motion arts or understanding when reading. It’s about what words convey in how they’re pronounced. It’s about the emotions they will generate for us humans.

Yes, an AI will do a decent translation. But it will inevitably miss out on the art of refining. It may fall flat, or miles away from what the author wanted to tell.

Now imagine an AI reading through code to generate a whole set of Diataxis documentation. It will fill-in the pages, no doubt. But then, don’t tell me to RTFM if you don’t WTFM yourself.

Featured image by Jonas Jacobsson.