DEV Community: Harshit Satyaseel

Database Replication vs Sharding: What They Are, When to Use Them, and How They Work Together

Harshit Satyaseel — Mon, 21 Sep 2026 10:30:09 +0000

Your database just crashed, and it was serving a million users. Their accounts, their orders, their data all gone. How do you get it back?

You would get it back if you had a copy of that data sitting somewhere else and that's exactly why techniques like Replication and Sharding exist. They solve different problems and work differently. Understanding when to use which one is something every developer and DevOps engineer should know.

Let's break them down.

What is Database Replication?

Replication is about making copies. You take your entire database and copy it across multiple machines (say, servers) running somewhere in the cloud or on-premises, so if one machine goes down, another one already has everything and can take over.

Here's how it works in practice.

Say you have one database machine running in the cloud, handling all the reads and writes for your application. That single machine is doing everything. Every time a user creates an account, places an order, or loads a page, the request hits that one server.

With replication, you copy that entire database to two or three other machines. Now you have multiple machines, and all of them hold the same data. You make one machine the primary, and it handles all the write operations like inserts, updates, and deletes. The other machines are called replicas, and their job is to handle read requests. When your application needs to fetch data, those read requests go to the replicas instead of all hitting the primary. The primary focuses on writes; the replicas take care of reads.

Now here's the real reason replication matters. If your primary machine crashes, a replica already has all the data, so it takes over right away. Your application keeps running, and users don't even notice that something went off. This ability to survive a failure without losing data or going offline is called fault tolerance, and it's one of the core reasons why replication exists.

Replication also gives you simpler backups. Since replicas hold a full copy of the data, you can take backups from a replica without putting any load on the primary server. In systems where read traffic is much higher than write traffic, like e-commerce product pages or content platforms, spreading reads across replicas makes the whole system faster.

Where replication hits a wall

Replication has a limit that becomes obvious as your application grows. Every write still goes through that one primary machine. No matter how many replicas you add, they only handle reads. So as your write traffic increases- more users signing up, more orders being placed, more data being updated- that primary server becomes a bottleneck. All the write pressure lands on one machine.

You can try upgrading the primary by adding more RAM, a faster CPU, or a bigger disk, and we call this vertical scaling. But those upgrades get expensive fast. A machine with double the power doesn't cost double the money; it costs significantly more. And at some point, there simply is no bigger machine you can buy. You hit the hardware ceiling.

On top of that, every replica stores a full copy of the entire dataset. If your database is, say, 5 terabytes, and you have three replicas, you're paying for 15 terabytes of storage just to hold the same data three times. Your writes can't scale, your storage costs keep multiplying, and upgrades only get more expensive. That's the issue replication runs into.

What is database sharding?

Sharding takes a completely different approach. Instead of copying the same data everywhere, sharding breaks the big data into smaller pieces and distributes each piece across different machines. Each piece is called a shard, and each machine holds only its portion of the total dataset.

Say your database has a users table with 10 million records. With sharding, you could split it so that users with IDs 1 through 5 million live on one machine, and users with IDs 5,000,001 through 10 million live on another. Each machine now stores and processes only half the data.

The field you use to decide which data goes where is called the shard key. In our example, the user ID is the shard key. Choosing the right shard key matters a lot — a bad choice can lead to one shard getting most of the traffic while others sit idle, which defeats the whole purpose.

Because each machine deals with less data, reads are faster; each shard only searches through its portion instead of scanning the full dataset. Writes benefit even more, because the write load is now spread across multiple machines instead of a single primary handling everything.

Since shards work independently, they can process reads and writes at the same time, in parallel. This is what gives sharding its real power. When you need more capacity, you just add another machine and redistribute some data. This way of scaling by adding more machines instead of upgrading one is called horizontal scaling, and unlike vertical scaling, it doesn't have a ceiling. You can keep adding machines as your data grows.

Sharding is also more cost-efficient at scale. Instead of paying for one massive, expensive server, you're using multiple smaller, cheaper machines that together handle more than any single machine ever could.

The trade-offs of sharding

Sharding isn't free of problems. It introduces complexity that replication doesn't have. The biggest one is cross-shard queries. If a query needs data that lives on two different shards, say you need information about user 100 and user 6 million in the same request, the system has to talk to both machines, fetch the data separately, and combine the results. These queries are slower and harder to optimise.

In databases like MongoDB, a component called mongos acts as a query router. Your application talks to mongos, and mongos figures out which shard has the data and routes the request. For queries that hit a single shard, this is fast. For queries that span multiple shards, there's overhead.

There's also the matter of fault tolerance. If a shard goes down, the data on that shard becomes unavailable. Unlike replication, where a copy can step in immediately, sharding by itself doesn't give you that safety net. You would have to recover the data from a backup, and until then, that portion of your system is down.

Using both together: How production systems actually work

This is why real production systems don't choose one over the other. They use both. The standard approach is to shard your database for scale, and then replicate each shard for fault tolerance. Each shard becomes its own replica set, a primary and two or more replicas holding copies of that shard's data.

MongoDB's production architecture is a textbook example of this pattern. A MongoDB sharded cluster has three components working together:

Shards hold the actual data. Each shard is deployed as a replica set, so every piece of data has copies for fault tolerance. If the primary of any shard goes down, one of its replicas is promoted automatically.

Config servers store metadata about the cluster, which data ranges live on which shard, how chunks are distributed, and where to route each request. Config servers are also deployed as a replica set for reliability. Mongos is the query router. Your application connects to mongos instead of directly to shards. mongos checks the config servers to figure out which shard holds the data, then routes the query there. If the query spans multiple shards, mongos handles the fan-out and merges the results.

This architecture gives you horizontal scaling from sharding and fault tolerance from replication. Each shard handles its portion of the data, and each shard's replica set makes sure that data survives failures.

When to use which

Not every application needs sharding. In fact, most applications start with replication and never need to go further.

Start with replication when your application is read-heavy, and your dataset fits comfortably on a single machine. A well-configured replica set can handle tens of thousands of reads per second, and it gives you fault tolerance and simpler backups with minimal operational complexity.

Consider sharding when your dataset has grown beyond what one machine can store, your write volume exceeds what a single primary server can handle, or you need to distribute data geographically across regions. Sharding adds real operational complexity, shard key design, query routing, and rebalancing, so it should be a response to an actual scaling problem, not a precaution.

Use both when you need scale and fault tolerance together, which is the case for most production systems handling large datasets. Shard for distribution, replicate each shard for safety.

Replication and sharding solve different problems, and understanding that difference is what separates a system that scales well from one that breaks under pressure.

Replication copies your entire database across machines. It gives you fault tolerance, faster reads, and simpler backups and is built for keeping your data safe and your application running.

Sharding splits your data into pieces across machines. It gives you horizontal scaling, parallel processing, and cost efficiency. It's built for handling data and traffic that outgrow a single server.

Self-Improving Docs, Part 1: Automatically Turning Documentation Gaps Into Pull Requests

Harshit Satyaseel — Fri, 18 Sep 2026 08:28:01 +0000

This blog is Part 1 of my series, Self-Improving Docs: Turning Gaps Into Pull Requests, on how I run documentation as a self-updating system.

In Part 2, I will go deeper into the docs assistant itself: how readers ask questions, how we handle feedback, and what we learned while building this experience. In Part 3, I will talk about the other half of the same problem, which is making the docs usable for coding agents through things like indexes, skills, and packaging. This post is about how I close the docs gap when readers fail to get a right answer.

Let’s start with the old process: before I built automation, the feedback loop was slow because it involved a lot of dependencies. Some readers hit an outdated page, which usually opened a ticket to a support engineer in Slack, and eventually the product team sent that message back to me. I used to fix the wrong doc page, publish the new one, and move on. That still happens, but what changed is the speed and the audience.

Now, AI agents read documentation a lot and differently from humans. A developer who opens an outdated page can notice the version looks wrong, ask a colleague, or check a changelog. An agent that lands on the same page does not usually pause and ask whether the page is correct; instead, it treats the docs as instructions and keeps going from that incorrect information. That is why outdated documentation stopped feeling like only an editorial problem and started feeling like a system problem.

Mintlify recently published survey findings that matched what I was already seeing in my own work.

A large share of teams still take a week or longer for a product change to show up in docs. Only about a quarter say it usually lands the same day. At the same time, most teams say AI agents now draft documentation updates for them, but only a small group lets those agents publish without a human in the middle. The interesting part is not the exact percentages.

Here, the interesting part is the pattern: people know documentation cannot keep up with product changes by writing and updating alone, and they are using agents to draft, while still wanting a human to decide what is true. That is the same place I ended up.

The problem was not “we need a chatbot”. A lot of conversations about AI and docs start with chat in my chat assistant. I built a docs assistant on our developer site, and readers use it every day. But chat by itself does not close the loop of missing and incorrect information. If the assistant cannot answer, and that failure disappears into a log nobody reads, you only built a nicer search box; that’s it. Well, I wanted it to know what’s wrong and self-update the docs. I wanted to understand: when the docs assistant cannot answer, or when a reader says the docs need an update, does that become work in the documentation repo?

If the answer is no, the bot is only an answer-giving machine and is not helping me close the docs gap loop. If the answer is yes, the bot becomes part of how documentation self-improves. So I built a system that self-improves.

What “closing the loop” means in real documentation

When I say closing the feedback loop, I mean this:

A reader asks a question on the docs site.
The assistant answers from the documentation.
If the answer looks missing, incomplete, or wrong enough that readers flag it, I capture that information as a data point.

This captured data can be used to open an automated documentation job that drafts a change and creates a pull request for me. The idea is that a human still reviews the PR and decides what to merge, but the hunting and getting feedback directly from the doc site is an insanely fast way to improve documentation.

I also capture feedback that never reaches the “not found” path. Readers can tag answers as helpful or not helpful, mark that something needs a doc update, report a bug, or send free-form feedback into Slack. Those signals matter because not every gap looks like a wrong answer. Sometimes the assistant answers confidently, and the reader still knows something is off. So I ended up with two kinds of input into the same system:

Automatic gap detection from the assistant response itself, when the reply looks like “not found” or only partial context
Human feedback from tags, escalation, and the feedback form; both of them are useful.

Automatic detection catches problems left out, and human feedback catches “the answer was there, but it was not good enough.”

If I draw the whole thing, it will look like this:

The important line in that diagram is the last one. The draft is not published. The PR is where I decide what is true and what needs to get merged.

How the auto-update mechanism works

The idea is simple. After the docs assistant answers, I ask one question: did the docs actually cover what the readers asked? I do not call a separate success API for that; instead, I read the answer itself. If it sounds like the topic is missing from the generated answer, or the model is saying it only has partial context, I treat that as a documentation gap.

When that happens, the system automatically sends the gap details to my backend with some information such as the reader’s question, the page they were on, and why I think the docs failed. From there, the backend starts a Mintlify agent job with that context.

The agent’s job is not only to refresh the live site. Its job is to draft the missing documentation, open a branch in the docs repo, and create a pull request. That PR is what I review. If the draft is good, I merge it, and if it needs edits, I edit and fix the missing part of it. If I feel that the gap is not a real docs gap, I close the PR and move on.

So the mechanism is:

Answer comes back
  → Detect gap from the answer text
  → Send question + page + reason to backend
  → Mintlify agent drafts a docs change
  → PR opens in the docs repo
  → Human reviews and merges

In code, the important part is the agent job call. Once any doc gap is detected, the backend asks Mintlify to draft from the failed question:

const res = await fetch(
  `https://api.mintlify.com/v1/agent/${projectId}/job`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${adminApiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      branch: `doc-gap-${Date.now()}`,
      asDraft: true,
      messages: [
        {
          role: "user",
          content: [
            `User asked: ${question}`,
            `Page: ${pageUrl}`,
            reason === "not_found"
              ? "This was not found in the docs. Please add or expand documentation."
              : "The assistant had only partial context. Please add or expand documentation where relevant.",
          ].join("\n"),
        },
      ],
    }),
  }
);
const jobId = res.headers.get("X-Message-Id");

That is the whole auto-update mechanism. A failed answer becomes context, and that context becomes a draft PR. Tech writers can still decide what ships.

What I have noticed is that most teams are fine letting agents draft documentation updates, but they still want a human deciding what gets published. That matches how I run it. The agent can open the PR, but the PR is not live docs yet. Someone still has to read the change, check whether it is accurate, and only then merge it. On a multi-product developer site like mine, that review step matters a lot, because one wrong sentence in the wrong product section is enough to break an integration for developers who use our docs.

Feedback is important

If I only talk about auto triggers, then this story is incomplete.

On my docs site, readers also send feedback deliberately. Sometimes they use tag chips under an answer, or they escalate to support when the assistant cannot help. They can also open the feedback option and write what is missing in their own words. Those messages go to Slack and into logging, so that I can see the exact wording instead of a vague “someone was unhappy.”

If I put the feedback mechanism next to the automatic one, it looks like this:

This matters because documentation gaps rarely arrive as one clean ticket. Most of the time it shows up as the same question asked again, an answer that only covers half of what the readers needed, or a short note like “this page assumes I already know X.” If that signal stays buried in chat history, nothing happens with it. But when the same note reaches Slack or a sheet with the page URL and the original question attached, it becomes useful data that a docs team can actually use for better documentation updates.

Think of feedback and auto triggers as two doors into the same room. One door is opened by the system when the answer looks empty. The other door is opened by the reader when the answer looks wrong or incomplete, and both must lead to documentation work.

How this feels different from old feedback process

In many companies and even in the company I work for, the older feedback mechanism depended on someone deciding the docs were worth a ticket. That still happens, and it is still valuable. What changed with a docs assistant is that the failure can be observed at the moment of asking and can be fixed automatically without pulling in a lot of people.

That is closer to how product teams ship. You do not wait only for support tickets to learn that a flow is broken. You look at where users drop. With this process, documentation can work the same way.

Mintlify’s report also talks about companies pointing agents at feedback and turning those signals into documentation patches.

Anthropic’s public story in that report is a good example of the same direction: collect signals, triage them, and turn the real documentation gaps into PRs while people still decide what ships.

Our version is built for our docs stack, but the idea is similar. Read the failure then draft a fix, review it and then merge it to publish.

What this does not solve

I want to be honest about the limits when it comes to auto updating the documentation, because otherwise this starts sounding like this is so easy so we all need to follow this process.

An agent job is only as good as the context you give it and the documentation truth underneath it. If the product behavior is unclear, the draft will be unclear too. Suppose, the question was actually a support issue or a configuration problem, opening a docs PR is the wrong way to update your docs. So, somebody still has to look at the PR and ask: is this a real documentation gap, or are we documenting around a product problem?

There is also noise. Automatic “not found” detection based on phrasing is useful, but it is not perfect. Sometimes the model hedges or the docs do contain the answer and RAG based retrieval missed it. It could also be that the reader asked something outside the product which is not documented at all. So the loop has to stay reviewable and easy to change.

And closing the loop on gaps is only one part of keeping docs updated. Product changes still need writers and engineers who notice what shipped. Version drift, naming consistency, and release notes still need their own updating systems. I will discuss this more in Part 3 of this series.

What changed in my day-to-day work

Before this mechanism existed, a weak docs answer mostly meant I would find out later, if at all. Now a wrong answer can show up as a concrete artifact: a logged question, a Slack escalation, a feedback note, or a draft PR waiting for me to review. This changed how I prioritize my work. Instead of only asking “which page should I rewrite or update this week,” I can also ask “which unanswered questions keep repeating” and “which draft PRs are actually fixing the same gap.” It does not remove writing but it changes where the writing starts.

Sometimes it starts from a blank outline or from a reader's question that already proved the gap exists. For me, that is the useful definition of docs systems work. You still own clarity and correctness and you also own the path from failure back into the repo.

Conclusion

Documentation used to be something we published and hoped people say all is correct and we never needs to update it. But, in real world that is not the case. Now that most of the modern docs systems also uses an AI assistant to answer reader's questions, if those systems hit a gap and nothing happens afterward, the gap stays invisible until someone catches and flag it. In this post I only covered the loop itself: detect the failure, capture feedback, draft the docs gap, and keep a human on the merge.

In Part 2 I will write about the docs assistant side in more detail, including how we collect information without turning every chat into noise. In Part 3 I will write about preparing the documentation for agents in the first place, so fewer questions fail before the gap even starts.

If you maintain developer docs and you already have an assistant on the site, I would start with one question: When the bot cannot answer, where does that failure go? If the answer is nowhere, that is the first system you need to build.

Linting Technical Docs for AI Readability Using Vale

Harshit Satyaseel — Thu, 17 Sep 2026 10:24:01 +0000

When I started learning more seriously about documentation for AI systems, I noticed something I had probably been ignoring for a long time. A lot of documentation problems are not really writing problems but are consistency problems.

The API is PlatformClient on one page and platformClient in an example on another. If you write technical documentation, you can relate to this.

In my docs, one feature is called Form Filling in the navigation, form filling in the body, and Form-Filling somewhere else.

Someone writes:

You might need to create a session before calling the API.

But the session is actually required. None of these things would make me reject a documentation page.

You might even read the page, understand what it means, and move on. But when you maintain a large documentation set, these small differences start showing up everywhere, and now that the same documentation is also being used by AI assistants and RAG systems, you need to start paying more attention to them.

Not because I think documentation should be written for AI. It should or shouldn’t, but if we can make the documentation clearer and more consistent for people, we also give machines cleaner information to work with.

That is where Vale comes in.

The style guide problem

Technical writers love style guides, and my docs also have one. We create them for everything like:

Capitalization
Product names
API terminology
Headings
Voice
Sentence length, etc.

Eventually, it becomes a large document which is hard to maintain, and something a person has to remember.

You can tell another writer:

Always use PlatformClient

Six months later, someone writes Platform Client

You can tell everyone not to use vague language in instructions.

Another writes you might need to.... This is normal when you have multiple writers, hundreds of pages, and documentation that keeps changing. Therefore, instead of putting a lot of rules in a document and hoping everyone remembers them, I started thinking about which rules could simply be checked automatically.

That is where I used Vale. Vale is a prose linter. It can run against Markdown and MDX and lets you define your own writing rules. It is basically the same idea as linting code it just that you are linting documentation here.

How do I start using Vale

Don’t start by creating 100 Vale rules. This is what most beginners do. Instead, the first rule is to protect information. Let’s understand this. Product names, API identifiers, important terminology- these are the things that should be written in a specific way.

For example, imagine that the official feature name is:

Form Filling

I don't want this appearing randomly across the documentation:

Form filling
form filling
Form-Filling

Sometimes lowercase form filling might be correct in body text, which is fine, but a good Vale rule should understand the context, not the rule itself.

For example, I might want Form Filling in a title but allow **form filling **in normal prose. Vale lets me create such rules instead of relying entirely on manual review.

A simple rule could look like this:

extends: existence

message: "Use 'Form Filling' in titles."
level: error

nonword: '\bForm filling\b'

scope: title

It is a very small rule. But that is the point. I don't need Vale to understand my entire documentation strategy; it just needs to catch the things I already know are wrong.

Vale language

There is another category that I find interesting in vale

Words like:

maybe
might
could
often
seems

These words are not automatically bad. Sometimes "might" is exactly the right word. But technical documentation has plenty of places where we use these words because we haven't been precise enough.

For example:

You might need to create a session before sending audio.

If the session is required, why say "might"?

Just say:

Create a session before sending audio.

So I can use Vale to flag words like might or could:

extends: existence

message: "Avoid vague language. Be specific."
level: warning

nonword: '\b(maybe|might|could|often|seems)\b'

scope: text

Notice that I used warning. I don't want the build to fail every time someone writes "could”, instead, I want the writer to stop for a second and decide whether the sentence can be made more precise, and this distinction matters a lot.

Vale for API identifiers

I am much stricter with API identifiers. If the actual SDK class is:

PlatformClient

then I want the documentation to say exactly that.

Not:

platformClient
Platform Client
platform client

The same goes for parameters:

emr_encounter_id
session_id

These aren't style preferences but are identifiers. If I get the capitalisation of a normal sentence wrong, nobody's application breaks, but if I get an API identifier wrong in a copy-paste example, there is a much bigger problem.

This is also where AI-generated code makes consistency more important. If an AI system gets PlatformClient from one page and platformClient from another, I would much rather have caught that inconsistency in the source documentation than try to fix the generated answer later.

Sentence length is another thing Vale can check. I like shorter sentences in technical documentation not because every sentence needs to be short, but because long sentences often contain several instructions that should have been separated.

For example:

Before calling the endpoint, make sure the session exists, that it is active, and that the session ID returned when you created it is the same ID you use in the request.

There are several pieces of information here.

I would probably write:

Create a session before calling the endpoint. The session must be active. Use the session_id returned when you create the session.

Much easier to scan, maintain, and reuse as individual pieces of information. I would still make sentence length a warning. I don't want a linter forcing writers to write unnatural prose just to make a number happy.

Where Vale actually fits

For me, Vale makes the most sense when it becomes part of the normal documentation workflow. As a tech writer, I can get feedback in the editor itself. The same checks can run before committing, and then CI can run them again when the documentation goes through a pull request.

A simple GitHub Actions job looks like this:

name: Vale

on: [pull_request]

jobs:
  vale:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: errata-ai/vale-action@v1
        with:
          files: '**/*.mdx'

When you work with Vale, be careful about what blocks a PR. An incorrect API identifier might be an error, or a vague word should probably be a warning. A style suggestion might just be a suggestion. If everything becomes an error, you will eventually start treating Vale as noise, and this gets frustrating over time.

Where Vale fits in AI workflow

I don't think Vale makes documentation "AI readable" in some special technical sense. What it does is help remove some of the mess from documentation, like consistent terminology, correct identifiers, etc.

My workflow has changed a bit with Vale. Now I also think about how another system might consume the same page. Developers might understand that Form Filling and form filling refer to the same thing. A documentation search system may still have to deal with the difference. But an AI assistant may retrieve several pieces of documentation and use them as context. Using value makes your source material less ambiguous to deal with. That is the real reason why linting is important in the AI world.

Conclusion

I have always thought of documentation quality as something that comes from many small decisions. Like:

Writing the right sidebar for an API.
The right example.

A clear heading that is easy to search and makes sense as per that page's topics. Vale doesn't replace any of that work. It just lets you automate some of the decisions we keep making manually over time, and as your documentation grows and gets consumed by AI systems, I think that is worth doing.

[Boost]

Harshit Satyaseel — Thu, 17 Sep 2026 06:18:44 +0000

Harshit Satyaseel

Sep 17

From Technical Writer to DevEx Engineer: The AI Shift in Documentation

#ai #documentation #devrel #devops

11 min read

From Technical Writer to DevEx Engineer: The AI Shift in Documentation

Harshit Satyaseel — Thu, 17 Sep 2026 06:12:02 +0000

With AI coming in, the shift in technical writing is rapidly changing. I used to always introduce myself as a technical writer, but not anymore. If you look at most of the JDs for tech writers, they don't feel like tech writer JDs. It feels like a DevEx engineer.

This shift is real because what I have been doing for the past couple of years, I totally relate to this, and I will explain why this is happening in this blog.

The shift

If I reflect on my work, most of my job does not look like “writing” anymore. Sometimes I am building style enforcement with Vale, putting quality gates around commits or designing docs for AI coding tools, debugging how assistants used our pages, and treating documentation like a developer product with release checks, failure modes, and ownership, and this is the shift I feel all the time.

AI did not replace my writing work, but I feel it definitely changed what my job role used to be. When docs became something humans, bots, and agents all consume together, the writer’s responsibility moved beyond publishing doc pages to owning how a developer interacts and feel with your published content.

Now, a tech writer needs to focus on developer experience and make sure they can find the right product, get the right answer, and use it without getting lost or misled. Writing is still part of technical writing, but it is not the whole role anymore. A big part of it has become DevEx engineering for documentation. Let's understand this more.

What “DevEx engineer” means for documentation people

Let's be clear about what I mean when I say the role is DevEx: I do not mean that it's a coding or backend engineering role.
DevEx in documentation, for me, is the work of making developers successful with a product integration.

For a long time, we used to think that only SDK engineers, API designers, or developer advocates had to take care of this, and we all treated documentation work as additional support material. This understanding does not hold anymore.

If your docs are wrong, outdated, hard to navigate, or easy for an AI tool to misread, developers fail in the same way they fail with a bad SDK error or a confusing API. So, docs are not support material but are part of the product experience, not an attachment around it now.

So when I say technical writers are moving into a DevEx role, I want to emphasise that: we still write, but now have to focus more on designing the system around the writing framework. We need to care about how developers discover, trust, and use what we publish.

With DevEx, we measure problems in developer outcomes, not only in “page is live.”

This is a big shift. We now write scripts, configure systems, define
rules for AI systems, and make sure that readers get what they need at the right time. This also brings down to one more challenge: we need to write and read code more than before.

The core skill of a tech writer did not change; we still need to understand the product and make it usable for developers. It's just that the toolkit we used to have around our skills got bigger because of AI.

The change in Job descriptions says it all

Open a few Technical Writer or Documentation Engineer JDs from the last few months, and you instantly notice sentences that used to live in other roles such as:

docs-as-code and CI familiarity
OpenAPI / SDK documentation experience
Information architecture for multi-product platforms
AI search, assistants, or “AI-ready documentation”
Style guides with automated linting and checks
GitHub workflows for automation and CI/CD

All of these make the JD less about we need a good tech writer to someone who can write well, but also takes care of entire doc systems to create a clean developer experience for the end readers.

Here is a simple way I think about old vs. new JD and the expectations it brings with this shift:

Older TW expectation	What the work often includes now
Write and update pages	Write new or update pages and keep product language consistent across the whole site
Follow a style guide	Enforce the style guide with tools like Vale
Publish after review	Pass checks before merge: links, anchors, validation, version drift
Support human readers	Support humans, docs assistants, and AI coding tools
Fix docs after feedback tickets	Catch failures earlier from bot chats, support teams, and broken journeys to fix automatically
Own content quality	Own content quality plus docs tooling and release processes in an automated way

If your company has multiple products under one docs site, this expansion happens even faster, and this is something I can say from my personal experience, where I handle multiple products under one docs site.

How my week changed as a technical writer

I still spend a lot of my time writing documentation, but it has drastically changed from what I used to do five years ago. Usually, my first draft is AI-driven now, followed by rigorous checks and reviews. Sometimes the docs are automatically generated from Docs Gap directly from the site, where I just review, make changes and publish.

For new docs that are written, I usually do this now.

1. Understand what shipped in the existing product
2. Update the docs pages led by AI and human review
3. Check whether naming and IA still hold for that new page
4. Run quality gates before merge
5. Think about how an AI tool or docs assistant will use this page to answer a human
6. Fix the failures that show up after publish

Sometimes the writing is normal too; for instance, when a new API comes for documentation, I talk to engineering, draft the guide using OpenAPI spec, edit examples, get it reviewed, and finally ship using the automated CI/CD process.

But sometimes it may look totally different. I get warnings from my automated checks that Vale is flagging terminology drift or that a change log is out of sync with a package version. An AI coding workflow needs a clearer skill or index, or a docs assistant is answering from the wrong product section in the RAG pipeline. Those days do not look like “technical writing” but more like a DevEx engineer who is trying to fix these problems.

This is a shift in role that not everyone is ready to adapt to.

Vale and style systems are not “nice to have” anymore

Let’s talk about Vale, because this is one of the clearest examples of the DevEx work. As you all know, Vale is a prose linter. You define its rules, and it checks your docs the way a code linter checks code. If the rule fails, the change can be blocked or skipped based on what you want to do when a new doc is pushed.

Earlier in my career, my manager used to say that style guides were mostly documents people were supposed to remember. Some teams followed them well, and some did not. Inconsistencies stayed in the site for months until someone flagged and tagged us via a ticket.
With AI writing content, it became a bigger problem because inconsistent naming fails RAG pipelines that my docs bot uses to retrieve content.

For example, if Product A’s auth concept is named one way on three pages and another way on two pages, a developer reading the docs may still guess, but a docs assistant or coding agent may pick the wrong meaning and give a wrong answer.

So in my work, Vale stopped being “grammar help” and became part of daily checks that run on every commit.

If you want to set it up, it will look like this in practice:

Protect exact product names and API/SDK names
Stop writers and AI drafts from rewriting code identifiers
Keep body writing rules separate from UI title rules
Catch banned vague phrases that hide missing detail
Make the style guide rules

I call this DevEx thinking, which is applied to language:

Human style guide
      ↓
Vale rules in the repo
      ↓
Same language across pages
      ↓
Fewer mixed-up answers for people and AI tools

I did not need to become a full-time engineer to do this. I treated documentation language like a contract and enforced it. This alone already pulls the role away from a technical writer who only writes the page.

Quality checks: treating docs like something you release

The second big change that I do almost all the time is maintaining a release discipline. Software teams do not merge backend code just like that. They run checks; PR are approved, etc. Same way I do for docs now. For example, if your docs say Package X is on version 1.2, but the package already shipped 1.4, developers will get confused.

If an AI tool reads that outdated page and generates integration code, the problem multiplies. If a heading change breaks deep links, both humans and assistants lose the citation path, and I have seen this happening with my docs.

So docs work starts to include checks, for example:

Terminology checks with Vale
Broken link and anchor checks on commit and PR merges
Docs site validation
changelog/package version drift checks using custom GitHub flows
A real review of product claims before publishing using PRs

You can imagine the flow like this:

flowchart TD
  A[Update docs] --> B[Vale / terminology]
  A --> C[Link and anchor checks]
  A --> D[Version / changelog drift]
  A --> E[Docs site validate]
  B --> F{Ready to merge?}
  C --> F
  D --> F
  E --> F
  F -->|No| G[Fix the docs system issue]
  F -->|Yes| H[Publish]
  H --> I[Humans + AI tools use it]

This is one reason JDs sound like DevEx. They are asking for people who can keep documentation reliable under change, not only people who can write a clear paragraph. For me, the mindset shift was simple: Publishing a page is not the finish line.

Passing the checks that protect developers is part of the finish line.

Designing documentation for AI coding tools like Cursor

This is something that feels newest to me. Developers are not only browsing docs sites now. They are also asking coding assistants like Claude or Cursor to implement from your documentation. Some teams now publish skills, MCP access, or curated indexes so tools can find the right pages faster.

This completely changes how you write and organize your pages now.

It is really important that you start asking questions like:

Is the task structure clear enough that a tool can follow create -> configure -> verify?
Are Product A and Product B separated cleanly in navigation and page titles?
Are auth concepts named exactly, every time?
Do we give agents a trusted map of important pages, or do we make them guess from a giant site?
Are examples complete enough that a model does not invent missing steps?

This is still documentation work. But it is documentation work with a second audience in mind: The AI Coding agents.

A useful way to think about it is as follows:

One docs repo
   ├── Human reader: skims nav, examples, tutorials
   ├── Docs assistant: retrieves pages into chat answers
   └── Coding agent: follows skills / tools / structured guides

If you only optimise for the human reading, the other two audiences feels left out and if you only optimize for machines, it is hard for human readers. So, how do we solve this? This is where thinking like DevEx engineer is keeping all three usable.

I will be honest: this part of the work can feel strange at first. You are writing for readers who do not get tired, do not ask clarifying questions the same way, and will confidently continue from a doc page that is wrong. That is exactly why structure, naming, and completeness matter more than ever now.

Docs assistants

A lot of modern docs site have AI assistant built in to ask questions related to docs. My doc site also has one. Once your site has an assistant on top of the docs, the assistant becomes another way developers experience your documentation. If it mixes Product A with Product B, or cites the wrong guide, that failure is attached to your docs IA whether you personally trained the model or not.

So tech writers needs to fix:

Reading chat failures
Deciding whether the fix is copy, IA, naming, or assistant behavior
Writing clearer product boundaries
Testing important questions again after a fix

This is one of the moments where the old title feels outdated. You are not only the person who writes the page but now you are part of the team making sure developers get the right help from the docs platform.

If you want the evaluation side of that work in more detail, I have written about docs-as-evals separately.

Here, the important career path is simpler: AI assistants made documentation failures visible in a new way. Visible failures create ownership and it pushes writers into DevEx-shaped work.

Skills technical writers need to add in this shift

If you are wondering what skills actually grow in this transition, this is the list I see from my own work and from those JDs:

Product and systems thinking

You need to stop thinking page by page and start think in journeys like onboard, authenticate, create a session, handle errors, upgrade versions, move between Product A and Product B.

Docs-as-code habits

Using Git, generating PR for reviews, branches, checks, and do not merge broken docs should be the part of your writing workflow. Not because you want to copy engineering processes but to keep things consistent. Docs break the same way code breaks when process is weak.

Tooling upgrades

Vale rules, validation commands, small scripts, config files, maybe a dashboard for assistant feedback. You do not need to build everything, but you need to add these in the repo may be my doing some coding work.

Information architecture under multi-product documentation

Shared words are dangerous in a complex product docs. Good IA and naming consistency become developer experience work. So, as a tech writer you need to decide and figure out what needs to get done to achieve this.

AI literacy for docs

Do no only focus on better prompt writing but also learn how assistants retrieve, how coding tools consume pages, where they fail, and what content patterns reduce those failures.

Collaboration with engineering and product on outcomes

You need to gather constant feedback on your docs work with engineering team to improve the process and consistency.

None of the above replace writing skill but they are the add ons to a tech writer now.

What did not change

Writing is not change. As a tech writer your core skill is still a strong structured writing. You need to write correctly both factually and conceptually. If the source docs are wrong, every assistant and coding tool will scale that wrongness. Honest limitations matter, talking to engineers are important and knowing when a sentence is hiding missing product truth is a key skill a tech writer needs to have.

AI did not remove the need for technical writers who understand the product but added pressure on those writers to also own the systems that distribute and interpret the writing. So the identity shift is not:

technical writer -> not a writer anymore

It is closer to:

technical writer -> technical writer + docs DevEx owner

If you are a new technical writer reading this

If you are new to this field, this is one of the best time to be a tech writer as it opens a lot of opportunities for you. You can develop these DevEX skills without rewiring your brain too much.

Here is a starting path that I would recommend:

Make your style guide enforceable. Put 5 to 10 high-value Vale rules around product names and confusing terms.
Add one quality gate that catches real pain. Broken links or version drift are good first gates.
Map your multi-product collisions. List words that mean different things in Product A vs Product B. Fix naming and nav around those first.
Watch how AI tools use your docs. Read assistant failures or ask a coding tool to implement from your guide, then fix what it gets wrong.
Redefine “done” with your team. Done should include the checks and follow-ups, not only the merged page.

Do this for a few months and your JD anxiety will make more sense. The industry is not randomly renaming roles as the the work changed, JD is catching up to that.

Conclusion

Technical writing is still the foundation of my work. I still write, edit, structure, and explain but AI changed the scope around that foundation. Docs are now read by humans, answered through assistants, and consumed by coding tools. That means the person closest to the docs often ends up owning consistency systems, release checks, AI-facing structure, and the failures that show up after publish.

That is why so many technical writer JDs feel like DevEx engineer JDs and this relate to the shift so strongly from my own last couple of years experience. If your title still says technical writer, that is fine. Keep learning and enjoy what you love.

Docs-as-Evals: The New Job Technical Writers Didn’t Expect

Harshit Satyaseel — Mon, 14 Sep 2026 10:37:34 +0000

When I started my career in technical writing, the requirements and expectations were simple: learn the product, talk to some SMEs or engineers, get the job done by completing the documentation work, and work on the collected feedback.

But with AI coming in, it doesn’t feel the way it used to. The role is shifting dramatically, and so are expectations. But why?

If you maintain a dashboard for your documentation insights, you must have noticed that AI agents now read your docs more than real humans do. This helps us understand the shift in the role. AI has changed the audience for our documentation. Real people still read docs, but agents read them more, mix them with chat history, and answer in your product’s voice. So “is this page clear?” is only half the review and feedback you get.

Let’s understand this better.

Last month, I noticed something in my bot’s chat history. The Docs AI answered all questions for a user’s query, but some of the links it shared back were wrong. The links did not belong to the context the user asked about. What I understood after my initial investigation was that the AI got stuck in the wrong documentation context, and the carried-over long chat history made it share the wrong link.

If a Docs bot answers incorrectly from your documentation, someone has to own the answer it responded with. That someone is the technical writer now. This is where the role is expanding now, and I call it docs-as-evals.

What docs-as-evals means for technical writers

If I explain this in simple language, it is the process of treating documentation quality as something you can test by asking real user questions against your docs, then testing whether the AI answer is correct or not.

With this process, we are trying to evaluate how the bot behaves in a certain way; for instance, we want to know:

Did it stay on the right product?
Are citations correct?
Did it keep conversation history as context when the user followed up
Did it drop the history when the user switched products?

These are important parameters to know, and technical writers are good at evaluating these things. We understand the mess and have data to check: which words users actually typed, which page is the real source of truth, etc. As tech writers, we always used to map these things in our heads and in the style guide. But now it needs to be used in evaluating AI answers.

Problems with RAG in developer documentation

Most of the product tech writers document are multi-product systems. The product that I document is also multi-product, and I have noticed that on a multi-product developer site like mine, RAG does not usually fail with a blank answer. It fails with an answer that reads correct but makes no sense.

One of the core problems that my docs assistant had was that it used to send a large conversation window on every turn. Great for follow-ups. Bad for product switches in multi-product documentation.

Let me make you understand with an example from my docs bot.

In my docs bot chat history, I saw a user ask questions about Ambient APIs, followed by how to create a session, then check headers, and status. Everything was fine until they asked something like, “How do I quick-start with Mobile SDK?”

For a human, that is a clear example of a new topic shift, but for the docs bot, it was still one long chat. So the old product messages stayed in the API request it sent, and the answer started mixing things up and producing wrong links.

In one real test I ran, that product-switch question was still carrying about nine earlier turns. After we changed how context was handled, the same question only carried about two turns, and it cleared the old thread. Same question. Better result that I will share with you at the end of this blog.

A few other problems around this that I noticed were:

Users do not ask with perfect product names. They say things like “the SDK” or “how do I authenticate?”

It's common in any product that different products share the same words, so a RAG-based chatbot usually gets confused. Handling this is a challenge because the current page, the chat history, and the new question can all pull the answer in different directions and scenarios.

So the issue was not only “write clearer docs.” The issue was also: when should the bot remember the old chat, and when should it forget it?

That is where docs-as-evals helped me.

How I started testing this

I made a simple list of real user questions from the bot history that I collected from my docs dashboard. For each question, I wrote what “correct” meant for me as a tech writer. My idea was to evaluate the following on the following parameters:

Which product should this answer belong to when the bot answers?
Is the new question a follow-up or a new topic?
Should I keep history, or should I drop it?

Think of this as a math set ok.

const selectionSet = [
{
prompt: "How do I create a session with Product A?",
expectProduct: "product_a",
keepHistory: false,
},
{
prompt: "How do I quickstart with Product B?",
expectProduct: "product_b",
expectMode: "topic_shift",
keepHistory: false, // drop Product A chat
},
{
prompt: "Tell me more about the authentication step",
expectProduct: "product_b",
expectMode: "follow_up",
keepHistory: true, // stay on Product B
},
{
prompt: "How do I quickstart with Product C?",
expectProduct: "product_c",
expectMode: "topic_shift",
keepHistory: false,
},
];
And this list became the golden set for me, which I used later to solve the problem.

What I checked in each answer

I kept the checks simple and evaluated the answers based on the following:

Did the docs bot stay on the right product for a topic shift? Were the right links shared?
For follow-ups, was the history kept or deleted?

If the user asked about another product and the bot linked other pages, I marked it as a fail. Even if the answer it gave was correct.

In code, it looked like this:

function isWrongCite(expectedProduct, citedPaths) {
if (!expectedProduct || !citedPaths.length) return null;
const matching = citedPaths.filter((path) =>
path.includes(`/${expectedProduct}/`)
);
// Fail if no links match, or most links are from the wrong product
if (matching.length === 0) return true;
return matching.length < citedPaths.length / 2;
}
// Example
isWrongCite("product_b", [
"/product_a/sessions/create",
"/product_a/authentication",
]);
// → true (wrong product links)
When I compared before and after on those key turns, the difference was clear. Product switches started landing on the right docs. Follow-ups stayed on the same product. The bot stopped dragging the old conversation into every new question.

When I compared before and after on those key turns, the difference was clear. Product switches started landing on the right docs. Follow-ups stayed on the same product. The bot stopped dragging the old conversation into every new question.

In those switch turns, the request size also dropped a lot in our runs, as you can see from the image below, from around 11k–17k characters to around 5k. This was because we stopped sending the wrong chat history with the questions.

What this means for the technical writer role

Technical writers never used to evaluate RAG-based systems. But now we do, and this is why I say the role is expanding. This is understandable: RAG is new, and most doc sites never used it. We still do the old work: learn the product, talk to engineers, write the docs, handle feedback.

But now, there is a new question we have to own and answer:

If the docs bot answers from our documentation, is that answer actually right?

That is docs-as-evals for RAG systems in documentation. In my day-to-day work, it looks like this:

I write docs, collect real questions from bot chats and support, then decide what correct looks like for those questions. I test them and use the failed ones to decide what to fix next, and this is something totally new to me. It is just documentation work for a world where AI reads our docs too.

Conclusion

RAG chatbots made it easy to get answers from long documentation, but they also created a new problem for technical writers to solve. Earlier, we mostly focused on information architecture to improve how a reader finds the right page. With RAG systems, that is not enough. We also have to check whether the AI finds the right answer, and that answer must be correct. I personally love this role change because it makes us more valuable in an uncertain world.

[Boost]

Harshit Satyaseel — Mon, 14 Sep 2026 07:00:43 +0000

Harshit Satyaseel

Sep 14

How to Build a Handbag Storefront with Storyblok and Next.js

#storyblokchallenge #react #tutorial #programming

10 min read

How to Build a Handbag Storefront with Storyblok and Next.js

Harshit Satyaseel — Mon, 14 Sep 2026 06:56:01 +0000

In this blog post, we'll build an imaginary Mira Carry, a small luxury handbag storefront website. We will manage marketing content in Storyblok, and Next.js will render the shop, blog, and a demo checkout. The finished Mira Carry home page, rendered from a Storyblok home story.

Note:

This tutorial assumes you are comfortable with React and the Next.js App Router. Basic knowledge of Storyblok is required.

This tutorial has been tested with the following package versions:

Package	Version
`next`	`16.1.6`
`react` / `react-dom`	`^19.2.4`
`@storyblok/react`	`^5.4.22`

If you want to explore the finished project first, open the live demo or clone GitHub repo

What we'll build
APIs we use
How Storyblok works with Next.js
Set up the project and render a story
Fetch a single story on dynamic routes
Build the product catalog with folder queries
Build category pages and product detail
Build the blog feed and resolve author relations
Enable draft mode and Visual Editor preview
Product images and the shop grid
Cart and demo checkout
Optional: seed content with the Management API
How the architecture fits together
Wrapping up
Additional resources

Overview

Storyblok lets you manage content separately from your code repo. In this tutorial, we'll use that to build a handbag website's content:

Home page modules
Catalogue across four categories, product detail pages,
Blog with author relations, and draft preview for editors.

Editors update content in Storyblok. Next.js fetches that content through the Content Delivery API and renders React components.

We'll start by setting up the Next.js project and rendering a story from Storyblok. Then we'll fetch stories on dynamic routes, list products with folder queries, resolve blog author relations, and add draft mode for the Visual Editor.

By the end, you'll have:

A home page built from nested bloks (hero, category_strip, product_grid, and more)
A shop catalogue of products under bags/, purses/, wallets/, and accessories/
Category landings and product detail routes
A blog index and articles with resolved authors
Draft Mode so editors can preview unpublished changes
A client-side cart and demo checkout (Next.js only — not Storyblok APIs)

APIs used in this tutorial

We'll talk to Storyblok through @storyblok/react and its apiPlugin. That client uses the Content Delivery API (CDN) v2. Optional seed scripts use the Management API v1.

Content Delivery API v2

Base URL (EU): https://api.storyblok.com/v2/cdn/…

Auth: STORYBLOK_DELIVERY_API_TOKEN (Preview or Public token)

Endpoint	Method	What we use it for	Parameters we pass
`/cdn/stories/{slug}`	GET	Home, about, product detail, category pages, articles	`version`, `resolve_relations`
`/cdn/stories`	GET	Blog index, shop catalog	`version`, `starts_with`, `sort_by`, `is_startpage`, `per_page`

Docs: Content Delivery API

`GET /cdn/stories/{slug}`

Fetches one story by full slug (home, bags/linen-tote, blog/priya-commute-tote, and so on):

Code example

await storyblokApi.get(`cdn/stories/${fullSlug}`, {
  version, // 'draft' | 'published'
  resolve_relations: 'article.author',
});

You'll see this pattern in:

src/app/[[...slug]]/page.js — catch-all pages
src/app/[category]/page.js — category landings (shop/bags, and so on)
src/app/about/page.js

`GET /cdn/stories`

Fetches multiple stories under a folder prefix.

Blog index (newest first):

Code example

await storyblokApi.get('cdn/stories', {
  version,
  starts_with: 'blog/',
  is_startpage: 0,
  sort_by: 'first_published_at:desc',
});

File: src/app/blog/page.js

Shop catalogue (one request per category folder):

Code example

await api.get('cdn/stories', {
  version,
  starts_with: 'bags/', // also purses/, wallets/, accessories/
  is_startpage: 0,
  per_page: 100,
});

File: src/lib/products.js (fetchAllProducts())

Parameter	Values we use	Why
`version`	`draft` or `published`	Draft Mode / Visual Editor vs production
`starts_with`	`blog/`, `bags/`, …	Limit results to a folder
`sort_by`	`first_published_at:desc`	Blog ordering
`is_startpage`	`0`	Skip folder index stories in lists
`per_page`	`100`	Catalog page size
`resolve_relations`	`article.author`	Inline the author story on articles

After a fetch with relations, applyResolvedRelations() in src/lib/storyblok.js swaps author UUIDs for full story objects.

Management API v1 (seed scripts only)

Base URL: https://mapi.storyblok.com/v1/spaces/{space_id}/…

Auth: STORYBLOK_MANAGEMENT_TOKEN

Script	What it does
`scripts/seed-full-catalog.mjs`	Creates product stories and category pages
`scripts/fix-bag-images-and-stories.mjs`	Updates blog copy and CMS asset URLs
`scripts/upload-storyblok-images.mjs`	Uploads images to Storyblok assets

Docs: Management API

What we don't use

API / feature	Notes
GraphQL API	We use REST through `@storyblok/react`
Commerce/checkout APIs	Checkout is a demo form under `src/app/checkout/`
Web-hooks in app code	ISR (`revalidate = 60`) refreshes cached pages

How Storyblok works with Next.js

Before diving in, let's first understand how all the pieces fit together. In Storyblok, content is made of blocks (bloks) and stories. Each story has a content.component type, for example page, product, or article.

The Demo_2 space: content types, nestable blocks, and how the home story nests bloks in body.

In our Next.js app, each blok maps to two things:

A React component (such as Hero.jsx or ProductGrid.jsx)
An entry in the storyblokInit({ components: { … } }) registry in src/lib/storyblok.js

At request time, a Server Component calls storyblokApi.get(…) on the Content Delivery API. Storyblok returns JSON for the story and its nested bloks. <StoryblokStory story={story} /> walks that tree and renders the matching React component for each blok.

A typical home story looks like this:

page (home)
  └── body[]
        ├── hero
        ├── category_strip
        ├── product_grid
        ├── testimonial
        └── story_strip

Set up the project and render a story

Install the project and render a story from Storyblok so we know that the setup works.

1. Clone and install

git clone https://github.com/meharshit/storyblok-interview-showcase.git
cd storyblok-interview-showcase
npm install
cp .env.example .env.local

2. Add your delivery token

In .env.local:

STORYBLOK_DELIVERY_API_TOKEN=your_preview_token
STORYBLOK_REGION=eu
STORYBLOK_API_BASE_URL=https://api.storyblok.com
DRAFT_SECRET=dev-draft-secret

You can find the Preview token under Storyblok --> space Demo_2 --> Settings --> Access tokens.

Tip: If the Blueprint wizard blocks Settings, skip the wizard and open the space settings URL directly, then copy the Preview token.

3. Initialise the SDK

In our repo, the file src/lib/storyblok.js registers blok components and configures the CDN client:

import { apiPlugin, storyblokInit } from '@storyblok/react/rsc';

export const getStoryblokApi = storyblokInit({
  accessToken: process.env.STORYBLOK_DELIVERY_API_TOKEN,
  use: [apiPlugin],
  components: {
    page: Page,
    hero: Hero,
    product_grid: ProductGrid,
    category_strip: CategoryStrip,
    // …
  },
  apiOptions: {
    region: process.env.STORYBLOK_REGION || 'eu',
  },
});

apiPlugin is what gives you storyblokApi.get('cdn/stories/…') against Content Delivery API v2.

4. Run the dev server

npm run dev

Open http://localhost:3000/. The catch-all route loads the home story and renders it — the same layout you saw in the screenshot at the top of this tutorial.

Fetch a single story on dynamic routes

File in the repo: src/app/[[...slug]]/page.js

URL path	Story slug sent to the CDN
`/`	`home`
`/about`	`about`
`/bags/linen-tote`	`bags/linen-tote`
`/blog/priya-commute-tote`	`blog/priya-commute-tote`

The core fetch looks like this:

const version = await getStoryVersion();
const { data } = await storyblokApi.get(`cdn/stories/${fullSlug}`, {
  version,
  resolve_relations: ARTICLE_RELATIONS, // 'article.author'
});
const story = applyResolvedRelations(data.story, data.rels);
return <StoryblokStory story={story} />;

getStoryVersion() returns draft when Draft Mode is on (and during local development), and published in production unless Draft Mode is enabled.

Caching uses export const revalidate = 60, so pages can refresh about every minute without a full redeploy.

Build the product catalog with folder queries

The shop page (/shop) lists product stories from four folder prefixes. It calls GET /cdn/stories once per category, there's no custom catalog endpoint.

Shop all: search, category filters, and product cards sourced from Storyblok folder queries.

File: src/lib/products.js

const prefixes = ['bags/', 'purses/', 'wallets/', 'accessories/'];

for (const prefix of prefixes) {
  const { data } = await api.get('cdn/stories', {
    version,
    starts_with: prefix,
    is_startpage: 0,
    per_page: 100,
  });
  // keep stories where content.component === 'product'
}

Each product story has fields such as title, price, description, and category. The shop UI turns them into cards with search and filters.

Build category pages and product detail

Category landing pages

Routes: /bags, /purses, /wallets, /accessories

File: src/app/[category]/page.js

Category landings are Storyblok page stories (for example shop/bags) with their own bloks.

Route	Story slug
`/bags`	`shop/bags`
`/purses`	`shop/purses`
`/wallets`	`shop/wallets`
`/accessories`	`shop/accessories`

await storyblokApi.get(`cdn/stories/${page.story}`, { version });

Those stories are page types. Their body can include product_grid and other bloks.

Product detail

Product URLs use the catch-all route. For example, /purses/chain-shoulder becomes:

GET /cdn/stories/purses/chain-shoulder

Product detail: title, price, and description come from the Storyblok product story.

The story’s content.component is product. Product.jsx renders it and handles add-to-cart.

Build the blog feed and resolve author relations

Blog index

File: src/app/blog/page.js

The blog index lists article stories under blog/, sorted by publish date.

await storyblokApi.get('cdn/stories', {
  version,
  starts_with: 'blog/',
  is_startpage: 0,
  sort_by: 'first_published_at:desc',
});

Keep stories where content.component === 'article', then link each card to /{full_slug}.

Article and author

Articles store author as a Stories field that points at authors/{slug}. When you fetch a single article, pass:

resolve_relations: 'article.author'

Storyblok returns related authors in data.rels. applyResolvedRelations() replaces the UUID with the full author object so Article.jsx can show name, bio, and avatar.

That relation string lives as ARTICLE_RELATIONS = 'article.author' in src/lib/storyblok.js.

Enable draft mode and Visual Editor preview

The Visual Editor needs the frontend to request version=draft. We'll use Next.js Draft Mode and a small API route for that.

Draft entry route

File: src/app/api/draft/route.js

GET /api/draft?slug=home&secret=YOUR_DRAFT_SECRET

The route validates an optional DRAFT_SECRET, calls draftMode().enable(), and redirects to the story path. To leave draft mode, hit GET /api/disable-draft.

Visual Editor URL

In Storyblok space settings, set the preview URL to your deployed site, or to:

https://your-site.vercel.app/api/draft?slug=home&secret=YOUR_DRAFT_SECRET

When an editor opens a story in the Visual Editor, Storyblok loads that preview URL so they can click components bridged with storyblokEditable.

Product images and the shop grid

For this demo, each story slug maps to a verified JPG in public/products/ through `src/lib/images.js. It still has Storyblok asset fields for later use.

js
export function resolveImageSrc(_image, { slug } = {}) {
return imagePathForSlug(slug || '');
}

For example:

js
'purses/clara-clutch': '/products/burgundy-gray-crescent.jpg',

The CMS still owns copy and structure; the frontend keeps product photography consistent. To change an image, add a file under public/products/ and update the slug map.

Cart and demo checkout

Cart state lives in React context (src/components/cart/CartProvider.jsx). It isn't stored in Storyblok.

Checkout page is a just UI, we have integrated any real payment method. This tutorial is focused on the Content Delivery API.

Feature	Implementation
Add to bag	Client state keyed by product slug
Cart drawer	`CartDrawer.jsx`
Checkout	`/checkout` — demo card form, no payment API

Optional: seed content with the Management API

If space Demo_2 is empty, you can seed it with a Management token:

export STORYBLOK_MANAGEMENT_TOKEN=sb_pat_...
export STORYBLOK_SPACE_ID=
node scripts/seed-full-catalog.mjs

The script creates stories with POST / PATCH on https://mapi.storyblok.com/v1/spaces/{id}/stories. Product photos on the site still come from public/products/ unless you also run upload-storyblok-images.mjs.

Caution:
Never put the Management API token in Vercel or commit it to Git. Use it locally for seeding only.

How the architecture fits together

By now you've built each piece of Mira Carry. So, let's understand them together.

The problem we solve in our demo

Marketing people can change the hero, featured products, and blog posts without asking a developer for a deploy every time.

The approach

We have used a headless CMS (Storyblok) for content and Next.js for the storefront. Marketing people work in Storyblok UI. The site reads JSON from the Content Delivery API and renders React components. Content and presentation stay separate.

Content is managed in Storyblok, delivered over the CDN API, and rendered by Next.js.

The content model

The Storyblok space is structured so editors can compose pages without touching code:

Content	How it's modeled
Home, about, category landings	`page` stories with a `body` field of nestable bloks (`hero`, `category_strip`, `product_grid`, …)
Products	`product` stories in folders (`bags/`, `purses/`, `wallets/`, `accessories/`)
Blog	`article` stories under `blog/`, each linked to an `author` story

That model is what makes the Visual Editor useful: editors nest and reorder bloks; the frontend already knows how to render each one.

How we fetch content

At runtime the app only talks to the Content Delivery API v2:

Need	API call
One page, product, or article	`GET /cdn/stories/{slug}`
Shop catalog or blog index	`GET /cdn/stories` with `starts_with` (for example `bags/` or `blog/`)

Auth uses STORYBLOK_DELIVERY_API_TOKEN. We pass version (draft or published) and, for articles, resolve_relations: 'article.author'.

The Management API is optional and local-only — seed scripts create stories; the live site never calls it.

How we render content

In src/lib/storyblok.js, storyblokInit registers every blok technical name to a React component:

react
components: {
hero: Hero,
product_grid: ProductGrid,
product: Product,
article: Article,
//
}

When Next.js fetches a story, <StoryblokStory /> walks the JSON tree. A blok with component: "hero" becomes <Hero /> with that blok's fields as props. If the Storyblok name and the registry key don't match, that block won't render.

How preview works

Editors need to see unpublished changes; visitors must only see published content.

/api/draft enables Next.js Draft Mode (optionally protected by DRAFT_SECRET).
getStoryVersion() returns draft or published.
Every Storyblok fetch uses that version.
The Visual Editor preview URL can point at the draft endpoint so clicks in Storyblok load unpublished content.

Wrapping up

You've now got a headless storefront that uses:

Content Delivery API v2 for runtime reads
@storyblok/react to map bloks to components
Relations for blog authors
Draft Mode for editor preview
ISR for production caching

Search, cart, and checkout stay in Next.js. They sit alongside the CMS without needing extra Storyblok APIs.

Technical Writers Can Make Your AI Prompts Better

Harshit Satyaseel — Mon, 14 Sep 2026 05:52:59 +0000

A few months ago, my engineering lead Slacked me a file: a system prompt for our new AI-powered note generator. He wanted me to look at that text file. I opened the file; the prompt felt like it was a lazy mess, bloated, ambiguous, and full of filler.

If they had used that prompt in production, every one of those extra words would end up on the API bill.
So, I took that prompt and spent about a week refactoring it using the same style guide, information architecture, and defensive writing rules that I use for my company's developer documentation. That was when I realised something:

Prompt engineering is not engineering at all. It is technical writing

The Sloppy AI writing

In software documentation, sloppy AI writing is mostly ineffective because it wastes tokens. When developers build LLM-powered features using prompts, they often treat the model like a human colleague.

I have seen devs writing prompts the same way they would write a message to a coworker on Slack. But that makes less sense for an LLM. An LLM does not read a prompt the way a developer reads a Slack message. It relies on the instructions and patterns in the text, so unclear and unnecessary wording can make the output less clear.

For example:

"Could you please be so kind as to analyse the following text very carefully,"
In the above prompt, you have just spent 15 tokens saying very little. I call this a lazy prompt. A lazy prompt is like a half recipe or, say, an easy recipe which unfortunately does not result in tasty food.

Why lazy prompts can crash your backend database

One of the biggest headaches our engineering team faced was parser failures. We needed the LLM to output raw JSON so our backend could ingest the data. Instead, the model kept returning conversational preambles:

"Sure! Here is the structured JSON clinical note you requested based on the transcript:"
{
"symptoms": ["cough", "fever"]
}
Because the model wrapped the JSON in markdown code blocks (json ...),

our backend parser threw a 500 error and crashed. The engineers’ first reaction was to write regular expressions and retry loops to strip out the markdown blocks and conversational text. But that resulted in another problem.

If the parser failed, the system automatically retried the API call, doubling the cost and latency for that transaction. Our production audits showed that 34% of our API calls were retries triggered by formatting failures. As a technical writer, my approach was to write defensively. What do I mean when I say this? Let’s understand with an example.

As technical writers, we don’t just tell users how to install a plugin. We also explain what to do when the installation fails. This is a defensive technique of writing. I applied the same thinking to that prompt and added explicit negative scenarios and error-handling patterns.

I removed conversational padding:

For example:

“Do not include introductory or concluding remarks. Do not say ‘Sure, here is the JSON.’ Return only the raw JSON object.”
Banned markdown blocks: For example: “Do not wrap the output in markdown code blocks (such as ```

json). Start the response directly with the opening curly brace {.
Defined empty states like: “If no medications are discussed, return an empty array []. Do not omit the key, and do not return null."

By writing defensively, we dropped our parser failure rate to near zero. We did not write a single line of regex or retry logic but just wrote better instructions, and that is what a technical writer does all day.

How large language models read and why layout is everything

In Technical writing, structure matters a lot. Writing in a structured manner gives readers a better mental model. For example, good structured writing will have a high-level overview at the top, step-by-step guides in the middle, and reference tables at the bottom. LLMs require the same kind of structured information.

Research from “Landmark research from Stanford and UC Berkeley (Liu et al., Lost in the Middle)” showed that an LLM’s retrieval accuracy drops significantly when key instructions or data sit in the middle of long, unstructured contexts.

The model pays the most attention to the beginning and the end of the prompt; the middle part is skimmed and scanned. To counter this middle-part attention degradation, as a prompt writer, it is important to structure your prompts like software specifications:

Role / System Persona (Head): Establish the context and behavioural boundaries.
Goal / Objective: Define the exact task to be performed.
Constraints (Negative & Positive): Set the guardrails, including what to do and what not to do.
Context / Input Data: Put the raw content to be processed inside clear XML tags, such as <transcript>...</transcript>.
Output Schema (Tail): Put the precise response format at the end, where the model’s attention is closest.

The point is not to make the prompt look neat, but to put the important instructions where they are less likely to get lost.

The “lazy” prompt vs. the “tech-written” spec: Comparison

To see these principles in action, let us look at a real-world scenario from my documentation. Imagine we are building an AI feature that parses unstructured clinical transcripts into a structured JSON format for an electronic health record (EHR) system.

The lazy prompt example:


plaintext
You are a helpful medical assistant. I am going to give you a transcript of a doctor talking to a patient, and I want you to extract the patient's symptoms and any medications they discussed.
Please put them in a JSON format so my system can read it. Make sure you are accurate and don't make things up. If there are no medications, just leave it blank.
Here is the transcript:
[Transcript content]

The Flaws in the above prompt:

Ambiguous Schema: “JSON format” is highly non-deterministic. The model may return {"symptoms": [...], "medications": [...]} in one run, and {"patient_symptoms": ..., "drugs": ...} in the next.
No Negative Scenarios: The model will almost certainly include conversational fillers like “Sure, here is the structured JSON for the transcript you provided:”, which will crash any standard JSON parser.
No Error Handling: “Leave it blank” could mean returning an empty string, an empty array, null, or omitting the key entirely.

How I would write this as a tech writer:


markdown
# Role
You are a clinical data parser. Your sole task is to extract symptoms and medications from clinical transcripts.

# Constraints
Output must be a single, valid JSON object matching the schema below.

- Do not include any conversational text, markdown formatting blocks (such as

 ```json), preambles, or postscripts.

- Extract only symptoms and medications explicitly stated in the transcript. Do not infer or extrapolate.

# Output Schema
{
"symptoms": ["string"], // List of symptoms explicitly mentioned. If none, return an empty array [].
"medications": [
{
  "name": "string", // Generic or brand name of the drug.

  "dosage": "string" // Dosage specified (e.g., "50mg"). If not specified, return "N/A".

}
] // List of medications. If none, return an empty array [].
}

# Input
Transcript: [Transcript content]

Let’s evaluate this prompt now:

Clear example: The explicit JSON schema and negative scenario guarantee that the output is immediately understandable by the AI.
Better Structure: The model has zero formatting decisions to make, dropping latency and eliminating reasoning cost.
Defensive writing: Clear instructions for empty states ([], "N/A") prevent the model from guessing or omitting keys.

Takeaway

AI has led to a quiet panic in the technical writing community, and many of the top-level executives think, why do we even need tech writers at all. We need to understand that the core skill of a technical writer is not just writing words; it is analysing complex software APIs, SDKs, and cloud systems, identifying edge cases, and constructing structured, unambiguous instructions.

As we move forward in the AI world, the demand for structured context architecture is going to skyrocket. Companies cannot build reliable AI features on top of sloppy AI content and conversational prompts. They need someone who treats language like code, and technical writers are the ones who understand information architecture best.

AI Agents Don't Read Your API Docs Like Developers Do

Harshit Satyaseel — Sat, 12 Sep 2026 06:20:59 +0000

I have spent a lot of my time writing API documentation, and I used to think that I understood what makes an OpenAPI specification good until AI came into the picture.

Good API docs are pretty straightforward: you define paths correctly, write the right types for parameters, and explicitly mark required fields, etc.

These are still important. But it starts to feel incomplete when a large share of your docs traffic comes from AI agents; good suddenly needs to mean something more. Look at my Mintlify dashboard. More than 50% of the traffic to my documentation site now comes from AI agents, and that changes the way I write the documentation.

When you give an API to an AI agent, you will notice different kinds of problems that did not exist before.

It needs to decide things like which operation matches a user's request, figure out what arguments are needed, understand relationships between operations, and sometimes recover when the API rejects its request.

Another problem is that an AI cannot build a mental model the way human developers do. Most AI has a tool definition and a context window. That difference changes how I think about OpenAPI now.

I'm not saying that an OpenAPI document magically becomes an LLM's system prompt. It doesn't. Depending on the stack, the specification may be transformed into function definitions, JSON Schema, MCP tools, or another representation before the model sees it.
The important part is what happens in between. The information in your API contract can become part of the information the model uses to decide what to do.

Once you look at it that way, a few things that seemed like minor documentation details start looking more like API design decisions.

The endpoint can be technically correct and still be bad for agents. Consider this example as a normal endpoint:


post:
  summary: Create encounter
  description: Creates an encounter.

There is nothing wrong with this OpenAPI. A developer who already knows the product might understand exactly what it means. But imagine an agent has access to several operations:



POST /encounters
GET  /encounters/{encounter_id}
GET  /encounters/{encounter_id}/sessions
GET  /encounters/{encounter_id}/artifacts
POST /encounters/{encounter_id}/complete

Now the user says: "Start a new visit for this patient."

The agent has to work hard to figure out that POST /encounters is the right operation.

The summary "Create encounter" gives it very little help. It doesn't tell the LLM that this is the operation it needs to use when starting a new visit. It also doesn't say what an encounter represents in this particular API. A more useful description would be something like:


post:
  summary: Start a new patient visit
  description: >
    Creates a new encounter for a patient visit.
    Use this endpoint when starting a new visit. The returned
    encounter_id identifies the visit and is required by the
    endpoints used to retrieve the visit session and complete
    the encounter. Do not use this endpoint to retrieve an existing encounter.

The above API description is not prompt engineering but better API documentation written for LLMs. The difference is that it contains information about intent and boundaries, not just implementation.

That distinction becomes important when an LLM has to read and choose between several operations that make the same sense.

APIs have always had workflows, but we didn't always put them in the contract

What I mean when I say this, well, let's figure it out. Look at a simplified clinical workflow as an example from my documentation:


Create encounter
       ↓
Start session
       ↓
Send audio
       ↓
Complete session
       ↓
Generate note

A developer working through the integration will usually discover the steps pretty quickly. The quick start probably shows it. The API reference explains the individual endpoints. There may be a tutorial that ties everything together. But AI does not necessarily get that same experience.

It may see five separate tools. Now suppose the model tries to send audio before a session has been created. The API returns an error. AI has to figure out what happened and what operation should come next.

As humans, we can make this easier by putting the relationship where it matters:


description: >
  Uploads audio for an existing visit session.
  The session must already exist and must be active.
  Use the session_id returned when creating the session.
  Do not call this endpoint before a session has been created
  or after the session has been completed.

Traditional API documentation often focuses on the happy path, like here's what this endpoint does.

Agent-facing documentation has another job: here's when this operation is valid, and here's when it isn't.

These are not the same thing.

The string problem is bigger than it looks. There is another pattern I see frequently in OpenAPI specifications:


status:
  type: string
This is technically valid, but it can throw away information that the API already knows.
If the only valid values are:
active
completed
cancelled
then the specification should say that:
status:
  type: string
  enum:
    - active
    - completed
    - cancelled

The reason is obvious for request validation, SDK generation, and documentation. It also matters when an agent is constructing the request. If the schema says string, the model has to determine what string belongs there. It may have seen the allowed values elsewhere, but there is no reason to make it guess when the API already has a finite set of valid values.

The same applies to dates, identifiers, numeric ranges, and other constrained values.

If something is a date, use a date format.
If there is a known pattern, express the pattern.
If certain values are accepted, use an enum.
Required fields must be marked as required.

This sounds almost too basic to be worth writing about, but there is an important principle behind it:

Every rule that exists only in prose is another rule the model may have to infer. That does not mean every possible business rule should be added to JSON Schema. Some rules are too dynamic or too complex for that. But when a constraint can be represented accurately in the schema, there is little benefit in leaving it implicit.

Descriptions should answer the question the model is actually trying to solve

One of the biggest changes I would make to API descriptions is to stop thinking of summary and description as places where we simply repeat the endpoint name.

For a human reader, this might be enough to start navigating.


summary: Get patient
For a model choosing between tools, it is much less useful.
Imagine an API has:
GET /patients/{id}
GET /patients/{id}/encounters
GET /patients/{id}/notes
GET /patients/{id}/medications

A user asks: "What happened during the patient's last visit?" Which one should the model call?

The answer is probably not obvious from the endpoint names alone. The API reference might have hundreds of pages explaining the system, but the model's immediate problem is much smaller:

Which tool is relevant to this intent?

So write descriptions that explain not just what an operation returns, but what kind of request should lead to that operation.

For example:


summary: Get encounters for a patient
description: >
  Returns the clinical encounters associated with a patient.
  Use this endpoint when you need to identify a patient's visits
  or determine which encounter to use for a follow-up operation.
  Use GET /patients/{id}/notes instead when the user is asking
  specifically for clinical notes.

It tells the reader not only what the endpoint does, but how it differs from a nearby capability. That is extremely useful when a tool set contains many operations with overlapping concepts.

There is a limit, though: don't turn OpenAPI into a prompt
Once you realise descriptions influence tool selection, there is a natural tendency to write big descriptions.

Something like:


description: >
  You are an expert healthcare API agent. Carefully analyse the
  user's request before using this tool. Think step by step about
  whether this tool is appropriate. If the user is asking about...

In the above example, the API contract is carrying instructions that really belong in the agent layer. This is where tools like Mintlify are handy. It features a ' For agents ' tag, allowing technical writers to include agent-specific instructions that remain hidden from human readers.

Also, maintaining such descriptions is a headache. As soon as the API changes, the description becomes stale, and suddenly your "prompt" is giving the model instructions that are no longer true.

I prefer a simpler rule:

Put facts and constraints in the API contract, whereas put general reasoning behaviour in the agent.

The API description should tell the truth about the operation. It should explain when it applies, what it requires, what it returns, and what can make it fail. The agent should decide how to reason over that information. That separation makes the system much easier to maintain.

Your error response is part of the conversation now

This is probably the part of agent-oriented API design that I find most interesting. For a traditional integration, an error response is often treated as the end of a failed request. For an agent, it can become the input to the next decision. Suppose the agent calls:


POST /sessions/123/audio
and receives:
{
  "error": "Invalid request"
}

There is not much context for the agent to act on that. It might think:

Should it retry or change the session ID
Ask the user
Check the session
Call another endpoint

Now imagine the API returns:


{
  "error": {
    "code": "SESSION_NOT_ACTIVE",
    "message": "Audio can only be uploaded while the session is active.",
    "field": "session_id",
    "current_status": "completed"
  }
}

That response gives the agent useful state. It knows the request failed because of the session state and understands which field is involved. Most importantly, it understands that simply retrying the same request is not going to help and that is why I think error design deserves more attention when APIs are exposed to LLMs.

A vague error like:


{
  "message": "Bad request"
}
is not only frustrating for a developer but also a dead end for an agent.
A structured error such as:
{
  "code": "SESSION_NOT_ACTIVE",
  "message": "Audio can only be uploaded while the session is active.",
  "field": "session_id"
}

gives the agent context to reason about. While it doesn't guarantee the model won't make mistakes, it provides actionable information instead of forcing it to guess.

The other problem nobody talks about: too many tools

There is one more lesson that becomes obvious when you write a lot APIs. Making every endpoint available to an agent is not necessarily a good idea. Imagine a mature API with 300 operations. A human developer might appreciate having all of them documented. They can search the reference, jump between resources, and use the API according to their needs.

An agent does not necessarily benefit from seeing all 300 operations at once.

Suppose the user asks: "Get the note for this encounter."

If the model has five tools related to notes, three related to encounters, and several generic document operations, tool selection becomes harder before the actual API call even happens.

So, we need to separate two ideas:

Your API surface is not necessarily your agent tool surface.
Your full OpenAPI specification can remain the source of truth for the API.

But the set of operations you expose to an agent can be deliberately selected.

This is also where OpenAPI and MCP start to overlap in interesting ways. Modern documentation and API tooling can selectively expose operations as tools instead of treating the entire API as one giant agent interface. Mintlify, for example, supports selecting OpenAPI operations for MCP exposure. The underlying idea is broader than any one documentation platform

Good agent design is partly about deciding what not to expose

What changed for me when writing API documentation? The reason I find this topic interesting is that none of these ideas is really new.
Strong API documentation has always needed clear descriptions, accurate schemas, good examples, sensible errors, and understandable workflows. What changed is the audience reading it.

When I used to write API documentation primarily for developers, I could assume that the reader would connect information across the documentation. A developer can read an endpoint reference, notice an unfamiliar field, search for it, open the related guide, and come back.

When an agent is choosing a tool, the cost of missing context is different. The model may never discover the missing page. It may simply choose the wrong operation. And that changes what I consider a good description now.

I no longer want an endpoint description to answer only:

What does this endpoint do?
I also want it to answer:
When should I use it?
What needs to be true before I use it?
What should I use instead when this is not the right operation?
What information do I get back that I will need later?

A checklist you should keep in mind

If I were reviewing an OpenAPI specification and knew it would be consumed by an agent, I would take a different approach. Here is a checklist you can follow.
Can I tell why this operation exists from its description? If the answer is just creates X or gets X, there may not be enough context for tool selection.
Can I distinguish this endpoint from similar endpoints? If several operations deal with the same resource, say what makes each one different.
Are the constraints represented in the schema? Don't leave an enum, date format, numeric range, or required field as tribal knowledge.
Are workflow dependencies visible? If one operation requires a resource or state created by another operation, document that relationship.
Can an error tell the caller what went wrong? A status code is useful, but a structured error can provide the information needed for recovery.
Does the agent really need every operation? A complete API is useful for developers. A focused tool set is often better for agents.

Conclusion

OpenAPI did not change, but its audience did. I don't think we need to change a lot in how we used to write OpenAPI docs. But when it comes to AI, the approach needs a little tweak. Developers still benefit from tutorials and cross-page context, but agents rely on the immediate, machine-readable facts in your documentation.

You should aim to make intent, constraints, workflows, and errors clear. Try this, and your API will be easier for both humans and LLMs to use.

I Stopped Sending the Whole Conversation to My RAG System

Harshit Satyaseel — Fri, 11 Sep 2026 06:46:40 +0000

If you’re building technical docs assistants using RAG pipelines, stop dumping the entire chat transcript into every prompt.

If you are currently appending full history, your pipeline is suffering from context bleed, where the LLM gets confused and mixes up parameters across completely different API endpoints. Plus, you are paying to resend 10,000 historical tokens to answer a 20-word follow-up.

Here is what I did to fix this in my RAG pipeline: I built a Scope-Adaptive Context Gate (SADCG).

Instead of stuffing the prompt, it classifies user intent and filters conversation history by topic scope before RAG retrieval even runs.

What happened after implementing this:
• 21% reduction in total per-chat credit cost
• Up to 40% lower peak context size
• Zero cross-topic hallucination in generated code and API answers

If you are building with RAG pipelines and struggling with context bloat, I wrote a full breakdown of the scope gate architecture, 5 classification modes, and implementation lessons.

Read the full story on Medium

DEV Community: Harshit Satyaseel

Database Replication vs Sharding: What They Are, When to Use Them, and How They Work Together

What is Database Replication?

Where replication hits a wall

What is database sharding?

The trade-offs of sharding

Using both together: How production systems actually work

When to use which

Self-Improving Docs, Part 1: Automatically Turning Documentation Gaps Into Pull Requests

What “closing the loop” means in real documentation

How the auto-update mechanism works

Feedback is important

How this feels different from old feedback process

What this does not solve

What changed in my day-to-day work

Conclusion

Linting Technical Docs for AI Readability Using Vale

The style guide problem

How do I start using Vale

Vale language

Vale for API identifiers

Where Vale actually fits

Where Vale fits in AI workflow

Conclusion

[Boost]

From Technical Writer to DevEx Engineer: The AI Shift in Documentation

From Technical Writer to DevEx Engineer: The AI Shift in Documentation

The shift

What “DevEx engineer” means for documentation people

The change in Job descriptions says it all

How my week changed as a technical writer

Vale and style systems are not “nice to have” anymore

Quality checks: treating docs like something you release

Designing documentation for AI coding tools like Cursor

Docs assistants

Skills technical writers need to add in this shift

Product and systems thinking

Docs-as-code habits

Tooling upgrades

Information architecture under multi-product documentation

AI literacy for docs

Collaboration with engineering and product on outcomes

What did not change

If you are a new technical writer reading this

Conclusion

Docs-as-Evals: The New Job Technical Writers Didn’t Expect

What docs-as-evals means for technical writers

Problems with RAG in developer documentation

How I started testing this

What I checked in each answer

What this means for the technical writer role

Conclusion

[Boost]

How to Build a Handbag Storefront with Storyblok and Next.js

How to Build a Handbag Storefront with Storyblok and Next.js

Table of contents

Overview

APIs used in this tutorial

Content Delivery API v2

GET /cdn/stories/{slug}

Code example

GET /cdn/stories

Code example

Code example

Management API v1 (seed scripts only)

What we don't use

How Storyblok works with Next.js

Set up the project and render a story

1. Clone and install

2. Add your delivery token

3. Initialise the SDK

4. Run the dev server

Fetch a single story on dynamic routes

Build the product catalog with folder queries

Build category pages and product detail

Category landing pages

Product detail

Build the blog feed and resolve author relations

Blog index

Article and author

`GET /cdn/stories/{slug}`

`GET /cdn/stories`