“It’ll Take Three Months” — A Short Story About Product Docs, Overengineering, and AI

Today, I asked one of my Product Managers to launch a product documentation website.

Nothing fancy.
Just a place where users can read how the product works.

Timeline: one day.

Before I left the office, I casually asked,
“So… how’s the doc site going?”

He looked at me, slightly nervous.

PM: “I’ve talked to the engineering team.”
PM: “They estimate… around three months.”

I paused.

Me: “Three months?”
Me: “For a documentation website?”

PM: “Yes. We’ll need frontend support, backend support, infra review…”
PM: “Also, can you provide the document types, paragraph structure, heading rules, and formatting guidelines?”

At that moment, something inside me snapped. Calmly. Politely. Internally.

Act 1: The Simple Version (That Somehow Sounds Radical)

I took a deep breath.

Me: “Listen. This is actually very simple.”
Me: “We can use GitHub Pages or VitePress. Markdown files. Static site.”
Me: “Deploy with CI. Done.”

The PM blinked.

PM: “But… how do non-engineers update content?”

Good question.
A classic one.

Act 2: The ‘Slightly More Grown-Up’ Version

Me: “Okay. If this is user-facing support content, we can use a Support Center.”
Me: “Like Jira Software uses Confluence.”
Me: “Docs, search, tickets, feedback — all together.”

The PM nodded.

PM: “That makes sense.”
PM: “But what if content changes very frequently?”

Ah.
Now we’re getting somewhere.

Act 3: Enter the Headless CMS

Me: “Then we introduce a Headless CMS.”
Me: “Not CRM. CMS.”
Me: “Contentful, Strapi, Sanity — pick one.”
Me: “Non-tech folks update content. Frontend just consumes APIs.”

The PM looked impressed.

Then asked the next inevitable question.

PM: “What if users still complain they can’t find answers.”

Of course they do. And how about you give me 50% of your salary in exchange for the stream of answers — I didn’t say it out loud.

Act 4: Search Is Not Enough Anymore

Me: “There are already solid solutions like Algolia — good old keyword search. Apply for access, let them crawl and index everything automatically.”
Me: “And yes, before you ask, we’ll also ride the AI Search wagon.”
Me: “Semantic search. Not ‘Ctrl+F’ on steroids.”

I explained how we could index docs into a vector database,
use embeddings,
and let users ask questions like humans instead of librarians.

The PM paused.

PM: “So… the AI just reads all our docs directly from the database?”

I sighed.

Act 5: How to Not Burn Production With AI

Me: “No. We don’t let AI freestyle.”
Me: “We use RAG — Retrieval Augmented Generation.”
Me: “Chunk the content. Add metadata. Control the context.”
Me: “If it’s not in the docs, the AI says ‘I don’t know’.”

The PM nodded slowly.

Then smiled.

PM: “What if the question isn’t about documentation… but about real data?”

The annoyingly right question.

Act 6: From ‘Docs’ to ‘Doing Things’

Me: “That’s where AI Agents come in.”
Me: “Docs answer how things should work.”
Me: “Agents check how things are actually working.”

I explained:

• Docs → RAG
• Orders, ERP, tickets → MCP tools
• Agent decides which one to use

Me: “The goal isn’t to answer questions.”
Me: “The goal is to solve problems.”

Silence.

Then the PM said:

PM: “So… this is not just a doc site anymore.”
PM: “It’s a product capability.”

Exactly. Let’s get real now.

Epilogue: What We Actually Built

Reality Wins.

We didn’t spend three months.

We didn’t write a 20-page formatting guideline.

We certainly did not train an LLM.

In fact, we shipped in one day.

We launched a VitePress site, hosted directly on GitHub Pages. With VitePress 2.0’s Edit this page feature, users can submit fixes via pull requests. They don’t just read the documentation — they participate in improving it.

For the Product Manager, the workflow is simple:

• add Markdown files

• update the route in the config

No backend. No CMS workflows. No permission maze.

For search, we integrated Algolia’s free keyword search. Fast, reliable, good enough and painless.

As for AI, we made a deliberate decision not to put it on the public doc site.

Instead, we integrated AI search and agents inside our own platform, where we can:

• control scope based on user roles

• manage token usage and cost

• connect safely to internal systems

It wasn’t the most “AI-hyped” option.

It was the right compromise.

And the results spoke for themselves:

Users stopped asking where the documentation was. Support tickets dropped. Engineers stopped being the search engine.

Moral of the Story

Documentation isn’t a website. It’s not just markdown, nor is it merely content. Documentation is a product, even a service. But is it aligned with your core value? Did you weigh it on a value-versus-effort scale? If it takes three months to launch a doc site, you aren’t short on engineering capacity - you’re short on product judgment.

If you’re a PM reading this and feeling slightly uncomfortable — good.
That’s usually where better judgment starts. 😄