<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0"><channel><title><![CDATA[World of Technical Writing]]></title><description><![CDATA[Practical guides on technical writing, API docs, docs-as-code and AI workflows for writers, by Harshit Satyaseel, documentation engineer and author.]]></description><link>https://tech-writing.hashnode.dev</link><image><url>https://cdn.hashnode.com/uploads/logos/6aa3a41bb290e89589f06fcf/7c338ca8-f3f9-47a5-8c39-37cebecc297c.png</url><title>World of Technical Writing</title><link>https://tech-writing.hashnode.dev</link></image><generator>RSS for Node</generator><lastBuildDate>Sun, 22 Nov 2026 15:37:26 GMT</lastBuildDate><atom:link href="https://tech-writing.hashnode.dev/rss.xml" rel="self" type="application/rss+xml"/><language><![CDATA[en]]></language><ttl>60</ttl><item><title><![CDATA[What Technical Writers Actually Do in 2027: Git, APIs, Scripts and AI Evals]]></title><description><![CDATA[Technical writers now work with Git, APIs, docs-as-code, scripts, and AI evals, yet many still see us as the ones who fix grammar.]]></description><link>https://tech-writing.hashnode.dev/what-technical-writers-actually-do-in-2027-git-apis-scripts-and-ai-evals</link><guid isPermaLink="true">https://tech-writing.hashnode.dev/what-technical-writers-actually-do-in-2027-git-apis-scripts-and-ai-evals</guid><category><![CDATA[Technical writing ]]></category><category><![CDATA[documentation]]></category><category><![CDATA[Career]]></category><category><![CDATA[AI]]></category><category><![CDATA[docs-as-code]]></category><dc:creator><![CDATA[Harshit Satyaseel]]></dc:creator><pubDate>Sun, 22 Nov 2026 03:30:51 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/covers/6aa3a41bb290e89589f06fcf/a7ef2d84-d43e-4aa3-a54d-16c7ad0878e8.png" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p>There's a side of being a technical writer that nobody really talks about openly, even though many of us experience it every single day. You're sitting with someone, they ask what you do, and you say, <em><strong>"I'm a technical writer."</strong></em> Almost immediately, they assume you write blogs, create content or fix grammar.</p>
<p>They have no idea what the role actually involves today. Behind that simple job title is a profession that demands Git, code fluency, API knowledge, documentation engineering, AI automation and the ability to work with increasingly complex technical systems.</p>
<blockquote>
<p>Despite these responsibilities, <strong>many technical writers still fight to have their work recognised, earn a seat at the table, and find a clear career growth path.</strong></p>
</blockquote>
<p>The gap between what people think technical writers do and what the profession actually demands has never been wider. Let's talk about this today.</p>
<div data-node-type="callout">
<div data-node-type="callout-emoji">💡</div>
<div data-node-type="callout-text"><p>If you are looking to upskill and become an AI-native tech writer, do check out my most comprehensive AI Native Tech Writer Career Kit . </p></div>
</div>
<p><a class="embed-card" href="https://satyaseel.gumroad.com/l/lugozs">https://satyaseel.gumroad.com/l/lugozs</a></p>

<p>I still remember the first time someone thanked me for "typing up the docs" after I had spent four days reading pull requests, setting up a local server, testing broken API calls, and chasing two engineers for missing error codes.</p>
<p>If you work as a technical writer, you probably know that exact feeling. You sit in a sprint review, and someone introduces you as <em><strong>"the person who handles the text."</strong></em> You point out a confusing step in a user flow, and someone brushes it off because, to them, you are "just a writer." That gap between what people think we do and what the job actually takes is the gap that nobody knows.</p>
<p>For decades, people have assumed <mark>this job is mostly about typing, formatting, and writing good English</mark>. They picture someone sitting at a desk, cleaning up sentences after the real engineering work is done. They do not see the planning, the testing, or the technical knowledge behind a single page. And now, with docs-as-code and AI changing how software gets built, that gap has grown wider than ever.</p>
<h2>Nobody knows the work behind a single page</h2>
<p>Most people outside documentation teams have no idea how a technical guide actually gets made. Most people have never heard of the <strong>Document Development Life Cycle (DDLC).</strong> They don't see the research that goes into understanding users, the planning behind every page, the decisions involved in structuring information, the technical reviews or the ongoing work required to keep documentation accurate after a product release.</p>
<p>They probably haven't come across DITA, topic-based writing or content reuse either. Think about what happens when a developer opens a guide, finds exactly what they need and gets their work done in five minutes. It looks like a simple page. But getting that page right takes much more than writing a few paragraphs.</p>
<p>It takes an understanding of the product, the user and how information should be presented.</p>
<blockquote>
<p>That's the irony of good documentation: the work behind it is often invisible. People rarely notice the structure, research or effort when everything works.</p>
</blockquote>
<p>They notice when a page is <mark>missing, a code sample doesn't work, or documentation hasn't been updated for a release</mark>. And when everything runs smoothly, it's easy to assume that creating documentation was the easy part.</p>
<img src="https://cdn.hashnode.com/uploads/covers/6aa3a41bb290e89589f06fcf/5dad0642-7ec8-4456-880e-383538c19848.png" alt="" style="display:block;margin:0 auto" />

<h2>Docs-as-code asked us to work like developers, without the respect</h2>
<p>Over the last decade, software documentation has changed significantly. Most software teams have moved to docs-as-code, moving documentation from Word files and standalone wikis into Git repositories alongside application code. This brought documentation closer to the development process, but it also changed what companies expect from technical writers. The role became much more technical, yet the way many organisations view and value it hasn't changed at the same pace.</p>
<p>Writing clear English is no longer enough. Technical writers are now expected to work with tools and technologies that were traditionally part of a developer's job. For example, we are expected to:</p>
<ul>
<li>Use Git confidently, work with branches, resolve merge conflicts and review pull requests.</li>
<li>Read application code, understand SDKs and work with OpenAPI specifications.</li>
<li>Run applications locally, test API endpoints and reproduce bugs before documenting them.</li>
<li>Work with static site generators, custom Markdown components and CI/CD pipelines.</li>
<li>Use AI to automate, create reusable skills and more.</li>
</ul>
<div data-node-type="callout">
<div data-node-type="callout-emoji">💡</div>
<div data-node-type="callout-text"><p>If you are looking for some of the best prompts to create skills and rules, do check out my 30 prompts for tech writers below.</p></div>
</div>
<p><a class="embed-card" href="https://satyaseel.gumroad.com/l/kmifnf">https://satyaseel.gumroad.com/l/kmifnf</a></p>

<p>Think about that for a moment. We are expected to understand code like developers, test features like QA engineers and explain complex systems in language that users can understand.</p>
<p>The expectations have changed, <em><strong><mark>but the recognition hasn't always followed.</mark></strong></em> Many organisations still classify technical writers as non-technical staff, even when the work requires a solid understanding of software engineering and development workflows.</p>
<h2>AI-native technical writing added even more engineering work</h2>
<p>Now with AI tools coming in, many people outside the documentation field assume technical writers have finally found a shortcut.</p>
<blockquote>
<p>The question came up everywhere: "Can't ChatGPT just write the documentation now?" Anyone who actually works in documentation knows that isn't how it played out.</p>
</blockquote>
<p>AI made generating a first draft faster, but it introduced a whole new set of responsibilities. We now have to think about how documentation is created, maintained, tested and consumed by both people and AI systems. Developers use coding agents such as Cursor, Claude Code and Codex to read documentation while building software.</p>
<p>AI search tools retrieve and summarise documentation to answer technical questions. Our content is <em><strong>no longer written exclusively for someone browsing a documentation website.</strong></em> It also needs to work as a reliable source of information for AI systems. That has changed the nature of our work. Technical writers are increasingly expected to:</p>
<ul>
<li>Write scripts and build automations that keep documentation in sync with application code.</li>
<li>Create custom linters and style rules to maintain consistency across documentation.</li>
<li>Prepare <em><mark>machine-readable content, including llms.txt for AEO, well-structured Markdown and reusable agent skills.</mark></em></li>
<li>Test how AI agents interpret documentation, identify where they get confused and fix gaps that lead to incorrect answers or outdated implementation guidance.</li>
<li>Build and maintain documentation tools, workflows and systems that support both human readers and AI agents.</li>
</ul>
<p>A growing part of our work now involves <strong>scripting, automation, information architecture, testing and building documentation infrastructure</strong>. Yet the perception hasn't caught up. While the responsibilities of technical writers continue to expand, many people still think our job begins and ends with fixing grammar and writing a few paragraphs.</p>
<h2>The hardest part: no career ladder and no seat at the table</h2>
<p>If you speak to technical writers in communities like Write the Docs, you'll hear similar frustrations from people working at both small startups and large tech companies. The burnout is rarely about writing itself. Most of us enjoy turning complex products into something people can understand. The <strong><mark>frustration comes from how companies treat documentation and the people who create it.</mark></strong> Here are three problems that I feel are most common:</p>
<ol>
<li><strong>Documentation is treated as an afterthought:</strong> In many companies, writers are brought in at the end of a sprint, when the UI is final, and the technical decisions have already been made. Instead of helping improve the user experience, we're expected to explain confusing workflows after the fact.</li>
<li><strong>There is no clear career path:</strong> Software engineers have well-defined growth paths, from Junior to Senior, Staff and Principal. Technical writers often hit a ceiling after one or two promotions. Many companies don't even have Staff or Principal Technical Writer positions. I've written more about this problem here: There Is No Ladder for Technical Writers.</li>
<li><strong>We're still treated as "just writers":</strong> When an engineer questions a confusing product workflow, it's seen as product thinking. When a technical writer raises the same concern, it's often overlooked. We're expected to understand the product deeply, but aren't always given the same voice in decisions.</li>
</ol>
<p>The frustrating part is that companies expect more from technical writers every year, but don't always give the role the recognition, authority or career growth it deserves.</p>
<img src="https://cdn.hashnode.com/uploads/covers/6aa3a41bb290e89589f06fcf/a2fdccfe-ad11-40f2-b29e-d8a25e249253.png" alt="" style="display:block;margin:0 auto" />

<h2>Why we stay, and what needs to change</h2>
<p>Despite all these frustrations, most technical writers genuinely enjoy what they do. We stay because we get to understand products deeply and help people use them better. In many ways, we're among the first people to experience a product from a user's perspective. Before a customer ever uses a new feature, a technical writer tries to set it up, follow the instructions and find what doesn't work.</p>
<p>We catch missing steps, confusing error messages and gaps in workflows that might otherwise go unnoticed. Good documentation also reduces support requests, helps developers integrate faster and gives customers a better experience. But if companies want better developer experiences and want AI coding agents to understand and use their products correctly, they need to start treating technical writing as an essential part of product development, not a service that comes at the end.</p>
<p>That requires a few mindset changes:</p>
<ul>
<li><strong>Involve writers early:</strong> Bring technical writers into product discussions, design reviews and API planning before implementation is complete.</li>
<li><strong>Create proper career paths:</strong> Introduce Staff and Principal roles for writers who build documentation systems, tooling and automation.</li>
<li><strong>Recognise the technical side of the role</strong>: Technical writers need product knowledge, code fluency and an understanding of how software works. Their contribution should be recognised accordingly.</li>
</ul>
<p>Technical writing has never been just about putting words on a page. It is about understanding complex systems, making them easier to use and helping people get real value from technology. The profession has evolved. It's time companies changed the way they see it.</p>
]]></content:encoded></item><item><title><![CDATA[Docsense: Best Open-Source Docusaurus Search Plugin 2027]]></title><description><![CDATA[Docsense is an MIT-licensed best Docusaurus search plugin that builds a static JSON index from Markdown and MDX with no crawler, account, or server.]]></description><link>https://tech-writing.hashnode.dev/docsense-best-open-source-docusaurus-search-plugin-2027</link><guid isPermaLink="true">https://tech-writing.hashnode.dev/docsense-best-open-source-docusaurus-search-plugin-2027</guid><category><![CDATA[docusaurus]]></category><category><![CDATA[Open Source]]></category><category><![CDATA[Technical writing ]]></category><category><![CDATA[plugins]]></category><category><![CDATA[documentation]]></category><dc:creator><![CDATA[Harshit Satyaseel]]></dc:creator><pubDate>Sat, 21 Nov 2026 08:46:10 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/covers/6aa3a41bb290e89589f06fcf/31c5c9f5-4216-4376-841d-438da90f47d5.png" length="0" type="image/jpeg"/><content:encoded><![CDATA[<div data-node-type="callout">
<div data-node-type="callout-emoji">💡</div>
<div data-node-type="callout-text"><p><strong>Project Links - Docsense</strong> (<code>docusaurus-plugin-docsense</code>) is an open-source search plugin for Docusaurus, released under the MIT license. You can check the code on <a target="_blank" rel="noopener" class="cursor-pointer ng-star-inserted" href="https://github.com/meharshit/docsense" style="pointer-events:none">GitHub</a>, try the <a target="_blank" rel="noopener" class="cursor-pointer ng-star-inserted" href="https://meharshit.github.io/docsense/" style="pointer-events:none">live demo and docs</a>, or install it directly with <code>npm install docusaurus-plugin-docsense</code></p></div>
</div>

<p>Building a static documentation site with Docusaurus comes with its own set of challenges. You need to organize your content, set up navigation, manage versions and configure deployment. But search is a different story.</p>
<p>Unlike many modern documentation platforms, <strong><mark>Docusaurus does not include a built-in search engine.</mark></strong> If you want readers to search across your documentation, you need to integrate a <strong>third-party service</strong>, configure an <strong>external crawler</strong> or build your <strong>own search infrastructure.</strong></p>
<p>Each option comes with some trade-offs. Hosted search services may require an application and approval. External crawlers can <mark>take time to index newly published content.</mark> Private documentation adds another challenge because external crawlers cannot access content behind authentication.</p>
<div data-node-type="callout">
<div data-node-type="callout-emoji">💡</div>
<div data-node-type="callout-text"><p>If you are looking to build your career as AI native Documentation engineer or you feel stuck as a normal tech writer, check out my <strong>end to end course below.</strong></p></div>
</div>
<p><a class="embed-card" href="https://satyaseel.gumroad.com/l/lugozs">https://satyaseel.gumroad.com/l/lugozs</a></p>

<p>What you really need is a search system that works with the way you already build documentation. It should index your Markdown files, update when you deploy changes and work without requiring a separate service to manage.</p>
<p><strong><mark>That is why I built Docsense.</mark></strong> It brings search directly into your documentation site, using your existing Markdown files without the overhead of maintaining separate search infrastructure.</p>
<h2>Search should be part of the build</h2>
<p>Docusaurus already processes your Markdown and MDX files during a production build to generate documentation pages. Those same files contain everything a search engine needs: page content, headings and structure. Most external search solutions take a different approach. <mark>They crawl your published website, extract its content and create a separate search index.</mark> This introduces another process to manage and another system that needs to stay in sync with your documentation.</p>
<p>There is no reason to make search a separate step when the content is already available during the build. Your documentation build can generate both the website and its search index.</p>
<h2>What is Docsense?</h2>
<p><strong>Docsense</strong> is an <mark>open-source static search engine built for Docusaurus</mark>. It reads your Markdown and MDX files during the production build and generates a lightweight JSON search index (<code>index.json</code>). The index is deployed alongside your documentation as a static asset. When someone searches your site, Docsense uses that index directly in the browser to find relevant content.</p>
<p>There is <strong>no external crawler</strong>, <strong>hosted search service</strong> or <strong>separate search server</strong> to maintain. Your search index is generated from the <strong>same source files as your documentation.</strong></p>
<h2>Getting started</h2>
<p>Getting started with Docsense is super easy and just takes three steps:</p>
<ol>
<li>Install the Docsense package.</li>
<li>Add the plugin to your Docusaurus configuration.</li>
<li>Run your production build with <code>npm run build</code>.</li>
</ol>
<pre><code class="language-plaintext">npm install docusaurus-plugin-docsense
</code></pre>
<p>JavaScript</p>
<pre><code class="language-typescript">// docusaurus.config.js
module.exports = {
  plugins: ['docusaurus-plugin-docsense'],
};
</code></pre>
<p>After the build finishes, the search bar <strong>appears in your navbar automatically.</strong></p>
<img src="https://cdn.hashnode.com/uploads/covers/6aa3a41bb290e89589f06fcf/93b4a1d5-ab15-4265-8248-11905437ea50.png" alt="" style="display:block;margin:0 auto" />

<p>Docsense generates the search index as part of the build process and deploy your site as usual. The search index goes live with it as soon as your build finishes.</p>
<div data-node-type="callout">
<div data-node-type="callout-emoji">💡</div>
<div data-node-type="callout-text"><p>Get my book on how to become an AI Native Technical writer here below.</p></div>
</div>
<p><a class="embed-card" href="https://satyaseel.gumroad.com/l/ai-native-technical-writing">https://satyaseel.gumroad.com/l/ai-native-technical-writing</a></p>

<h2>Indexing of pages</h2>
<p>Docsense generates the search index during <code>docusaurus build</code>, so it always stays in sync with your documentation. When you update a page, its <mark>search entry is updated in the same build and deployed alongside your site</mark>. No separate indexing process or deployment is needed.</p>
<img src="https://cdn.hashnode.com/uploads/covers/6aa3a41bb290e89589f06fcf/3b5dd1a4-3b3b-4c53-a786-c2e483c17dfb.png" alt="" style="display:block;margin:0 auto" />

<p>Docsense reads your Markdown and MDX, writes the static index, and lets it deploy alongside the rest of your site. You do <strong>not schedule a crawl,</strong> and you <strong>do not wait for one.</strong></p>
<h2>What a reader sees</h2>
<p>Say a reader opens your docs late in the evening and presses <code>⌘K</code> (or <code>Ctrl+K</code>). They type a few words, and a modal lists the exact sections that match. Each result shows its breadcrumbs and a short snippet so the reader can tell whether it answers their question before clicking.</p>
<img src="https://cdn.hashnode.com/uploads/covers/6aa3a41bb290e89589f06fcf/8214f145-03a4-461e-a092-c4c486be1bc5.png" alt="" style="display:block;margin:0 auto" />

<p>Search results take readers directly to the relevant <strong>H2 or H3 section instead of always opening the page from the beginning.</strong> This makes it easier to find specific information in long guides with multiple sections.</p>
<p>Docsense also makes search more flexible with the following features:</p>
<ul>
<li><strong>Typo tolerance:</strong> Finds relevant results even when readers make spelling mistakes. For example, searching for <code>"instaling plugn"</code> can still return <code>"Install the plugin"</code>.</li>
<li><strong>Word stemming:</strong> Matches related word forms. For example, searching for <code>"installing"</code> also returns results containing <code>"install"</code>.</li>
<li><strong>On-page highlighting:</strong> Highlights the search terms on the destination page, helping readers quickly identify the relevant content.</li>
</ul>
<img src="https://cdn.hashnode.com/uploads/covers/6aa3a41bb290e89589f06fcf/dea496e0-bac3-47da-b05b-8a0db711a421.png" alt="" style="display:block;margin:0 auto" />

<p>The search modal also lets readers filter results by page type, such as <strong>Docs</strong>, <strong>How-to</strong> and <strong>Tutorial</strong>. Docsense identifies these types from your file paths or frontmatter. It also supports Docusaurus versioning and multiple languages. Readers can choose how many results to display, from 3 to 20, with <strong>8 results</strong> shown by default.</p>
<div data-node-type="callout">
<div data-node-type="callout-emoji">💡</div>
<div data-node-type="callout-text"><h3>If you work in technical writing domain and feel stuck, this is what else I do</h3><p>I am a documentation engineer who helps technical writers move into API documentation and AI-assisted docs work. Connnet with me for <strong>1:1 Career Mentorship,</strong> Career mentorship, mock interviews for technical writing roles, and resume and portfolio reviews.</p></div>
</div>
<p><a class="embed-card" href="https://topmate.io/harshit_satyaseel">https://topmate.io/harshit_satyaseel</a></p>

<h2>Customize the Docusaurus search experience with Docsense</h2>
<p>Your search interface should feel like part of your documentation site, not an external tool. Docsense <strong>lets you customize UI labels</strong>, keyboard shortcuts and <strong>CSS variables</strong> to match your existing Docusaurus theme.</p>
<p>The search index is also a plain JSON file. You can open <code>index.json</code> to inspect exactly what content is included in search. This makes it easy to audit indexed pages and verify what readers can find. Unlike hosted search services, Docsense gives you direct access to the index generated during your build.</p>
<h2>Docsense fits into your existing docs-as-code workflow</h2>
<p>Docusaurus documentation typically lives in Git and follows a familiar workflow: pull requests, code reviews and CI builds. Search should follow the same process.</p>
<p>Docsense generates the search index from the same Markdown and MDX files used to build your documentation. When a page changes, <mark>its corresponding search entry changes in the same build.</mark> There is no separate crawler to schedule, external index to update or second system to keep in sync.</p>
<h2>Keep private Docusaurus documentation within your network</h2>
<p>Docsense <mark>runs entirely within your build environment.</mark> It does not send your documentation to an external crawler or cloud-hosted search index. Your content stays within the environment where you build and deploy your site. There is <strong>no vendor approval process,</strong> external account or separate indexing service to configure. The generated index is part of your own deployment, so you control where it is stored and who can access it.</p>
<p>Keep in mind that the search index follows the access controls of your deployed site. If your documentation requires authentication, you must protect the generated index with the same access controls.</p>
<h2>Docsense limitations and when to choose hosted search</h2>
<p>Docsense uses a static JSON index that is downloaded and searched in the reader's browser. This keeps the infrastructure simple, but the <strong>size of the index matters</strong>. If you maintain a very large documentation site, test search performance and index download size against your actual content before adopting it.</p>
<p>Docsense is a good fit when you want:</p>
<ul>
<li>Search generated directly from your Docusaurus Markdown and MDX files.</li>
<li>A fresh search index with every production build.</li>
<li>A static JSON index that you can inspect and control.</li>
<li>No external crawler, hosted search server or separate indexing pipeline.</li>
</ul>
<p>A hosted search platform may be a better choice if:</p>
<ul>
<li>You need managed search analytics and cloud infrastructure.</li>
<li>You already use Algolia or another hosted search provider across multiple products.</li>
<li>You want integrated Ask AI or conversational search capabilities.</li>
<li>You need to search across multiple products, websites or content sources beyond your Docusaurus documentation.</li>
</ul>
<h2>Conclusion</h2>
<p>The easiest way to evaluate Docsense is to install it, build your documentation and try searching your own content. Once the build is complete, open your site and press <code>⌘K</code> on macOS or <code>Ctrl+K</code> on Windows and Linux to open the search modal.</p>
<p>Docsense is an open-source project, and feedback from developers and documentation teams will help shape its development.</p>
]]></content:encoded></item><item><title><![CDATA[Improve AEO - How to Write Developer Documentation for AI Agents and LLMs]]></title><description><![CDATA[Learn how to write AI-ready developer documentation for coding agents and LLMs with before-and-after rules for headings, tabs, OpenAPI, and llms.txt.]]></description><link>https://tech-writing.hashnode.dev/improve-aeo-how-to-write-developer-documentation-for-ai-agents-and-llms</link><guid isPermaLink="true">https://tech-writing.hashnode.dev/improve-aeo-how-to-write-developer-documentation-for-ai-agents-and-llms</guid><category><![CDATA[aeo]]></category><category><![CDATA[Technical writing ]]></category><category><![CDATA[llm]]></category><category><![CDATA[AI]]></category><category><![CDATA[documentation]]></category><category><![CDATA[technology]]></category><dc:creator><![CDATA[Harshit Satyaseel]]></dc:creator><pubDate>Fri, 20 Nov 2026 14:23:33 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/covers/6aa3a41bb290e89589f06fcf/2f2e98c5-ae7d-4fb8-b70e-9e0117735c0e.png" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p>I talk to a lot of developers to understand how they use developer documentation in their day-to-day workflows. One pattern comes up all the time: they open their IDE like Cursor or VS Code, point a coding agent at a developer portal and ask it to build an integration.</p>
<p>Check your docs AEO score using the following app.</p>
<p><a class="embed-card" href="https://docs-aeo-scorer-web.vercel.app/">https://docs-aeo-scorer-web.vercel.app/</a></p>

<p>The agent reads the documentation, follows the information architecture and structure you've carefully designed, and still ends up calling a deprecated endpoint, choosing the wrong SDK or inventing an import path that doesn't exist.</p>
<p><mark>Have you ever wondered why this happens and, more importantly, how to fix it? Let's learn this in this article.</mark></p>
<hr />
<h2>Problem with Traditional Documentations</h2>
<p>The problem with traditional documentation is that it was designed for human readers, not AI agents. We have spent years optimising documentation for visual navigation, page hierarchies and human browsing, rather than machine retrieval, parsing and accurate context extraction.</p>
<p>Here's something I've learnt over time: <strong><mark>Documentation that works well for someone clicking through a portal doesn't necessarily work well for an AI agent consuming it in chunks.</mark></strong></p>
<p>Think about how developers interact with documentation. A human reader can scan the sidebar, switch between tabs, follow breadcrumbs, connect information across multiple pages and recognise when a code example looks outdated. They can use the entire visual context of a rendered page to understand what to do next.</p>
<blockquote>
<p><mark>Coding agents don't work that way.</mark></p>
</blockquote>
<p>When an LLM or IDE assistant reads your developer portal, it often retrieves raw <strong>Markdown or plain text</strong>, breaks pages into <strong>smaller chunks</strong> and <strong>retrieves only a handful of context</strong> relevant to the current query. It relies heavily on <strong>headings</strong>, <strong>opening sentences</strong> and <strong>surrounding context</strong> to understand what each section contains. It may never see the content hidden inside tabs unless that information is explicitly exposed in an agent-friendly format. When important context is missing, <mark>the agent fills in the gaps.</mark> It <mark>guesses</mark> import paths, SDK versions, parameter values and implementation details. That's how you end up with generated code that looks perfectly reasonable but doesn't actually work.</p>
<blockquote>
<p><mark>This changes how we need to think about documentation.</mark></p>
</blockquote>
<p>Every section, heading, link, code block, OpenAPI description and even every line in your <code>llms.txt</code> file should make sense when retrieved independently, read out of order and consumed without the visual context of your documentation portal.</p>
<p>In this guide, I'll walk you through practical Before and After examples and a set of writing rules you can start applying to your existing documentation right away.</p>
<p>More importantly, writing AI-readable documentation is only the starting point. It forms the foundation of a <strong>modern</strong> <a href="https://medium.com/gitconnected/designing-docs-for-coding-agents-a-practical-guide-to-answer-engine-optimisation-aeo-76a53b2f39c8"><strong>Answer Engine Optimisation (AEO)</strong></a> <strong>stack</strong>, where a strict documentation style guide works alongside agent skills, a Documentation MCP server and targeted integration recipes. Together, these give coding assistants access to verified implementation workflows instead of leaving them to piece together answers from disconnected documentation pages.</p>
<div data-node-type="callout">
<div data-node-type="callout-emoji">💡</div>
<div data-node-type="callout-text"><p>If you are looking to build your career as AI native Documentation engineer or you feel stuck as a normal tech writer, check out my <strong>end to end course below.</strong></p></div>
</div>
<p><a class="embed-card" href="https://satyaseel.gumroad.com/l/lugozs">https://satyaseel.gumroad.com/l/lugozs</a></p>

<h2>Why classic UI pattern confuse AI</h2>
<p>Traditional documentation interfaces use several layout patterns that look great to human readers but create problems when the same content is consumed by AI agents. UI elements often lose their structure when a documentation scraper or ingestion pipeline converts a webpage into plain text or smaller content chunks.</p>
<p><mark>I've found that four common UI patterns are responsible for a large share of these retrieval problems.</mark></p>
<h3>Collapsible and tabbed content</h3>
<p>Tabs make perfect sense when you're designing documentation for developers. A reader can switch between programming languages, compare SDK implementations or explore different integration options without leaving the page.</p>
<p>But here's the problem: many documentation scrapers and retrieval pipelines capture only the default tab or the initially rendered content. They don't necessarily extract every tab or follow every interactive state. This means that if you put an important authentication requirement, rate limit or workflow constraint inside the second or third tab, there's a good chance the coding agent will never see it.</p>
<p>The fix is not to get rid of tabs altogether. It's to be more intentional about where you use them. Use tabs when you're presenting equivalent implementations of the same task across different programming languages. For distinct workflows, conceptual differences or important implementation requirements, use separate H2 or H3 sections, standalone pages or accordions for supporting details.</p>
<p>If you still want to retain tabs for a better human reading experience, provide an agent-facing summary that explicitly describes what each tab contains. For example, <mark>Mintlify supports</mark> <code>&lt;Visibility for="agents"&gt;</code><mark>, which lets you expose additional context specifically for AI agents.</mark></p>
<p>The goal is simple: <strong>Never make an AI agent depend on clicking a UI element to discover information it needs to implement an integration correctly.</strong></p>
<img src="https://cdn.hashnode.com/uploads/covers/6aa3a41bb290e89589f06fcf/cc63343b-d19f-4122-b1dc-27c60847cc5b.png" alt="" style="display:block;margin:0 auto" />

<h3>Vague and directional links</h3>
<p>Phrases like <strong>"click here," "see below," "refer to the section above"</strong> or <strong>"check the left panel"</strong> depend on visual context. They make sense when someone reads the entire page in a browser, but lose their meaning when a retrieval pipeline extracts a few paragraphs from the middle of a guide.</p>
<p>An AI agent retrieving an isolated chunk has <strong>no reliable way</strong> to know what "below" or "above" refers to. Every link label should name its exact destination and make sense independently of the surrounding content.</p>
<h3>Multi-page tutorials that assume memory</h3>
<p>Tutorials often assume that readers have followed previous steps and remember the context. Instructions like <strong>"continue from the previous page,"</strong> <strong>"use the token you generated earlier"</strong> or <strong>"as shown in step two"</strong> become unreliable when semantic search retrieves only page three of a four-page quickstart.</p>
<p>Every page and major section should provide the context required to understand and complete the task independently. Restate essential inputs, such as token type, base URL and resource IDs, in one clear line rather than assuming the agent has access to earlier pages.</p>
<h3>Screenshots of code and diagrams without a text equivalent</h3>
<p>Coding agents <strong><mark>cannot reliably extract text</mark></strong> embedded inside PNGs or static SVGs. Screenshots of code are even less useful because their contents cannot be directly copied, linted or executed.</p>
<p>Always use fenced code blocks for code examples. When an architecture diagram helps human readers understand a system, pair it with a structured text description or a Mermaid equivalent inside an agent-visible block. This ensures the same technical information remains accessible when the image is excluded from the retrieval context.</p>
<h2>Self-contained sections: headings and pronouns</h2>
<p>Retrieval engines weight headings and opening sentences heavily when matching a <strong>developer's prompt to a documentation chunk.</strong> If your heading is generic and your first sentence starts with <mark>an ambiguous pronoun</mark>, the chunk loses its meaning the moment it leaves the page.</p>
<p>Follow these rules when structuring every page and section:</p>
<ul>
<li><strong>Make headings task-explicit or outcome-explicit:</strong> Replace vague labels like <code>Overview</code> or <code>Configuration</code> with specific actions or concepts.</li>
<li><strong>Match phrasing to content type:</strong> Use verb-led phrases for procedures (<code>Authenticate API requests</code>) and precise noun phrases for concepts (<code>Webhook signature verification</code>).</li>
<li><strong>Separate heading case from UI chrome case:</strong> Use sentence case for body headings (<code>## Set the base URL and partner ID</code>) and reserve Title Case for UI chrome labels such as tab titles, step titles, and card titles.</li>
<li><strong>Omit question marks from explanatory headings:</strong> Write <code>## How authentication works</code>, never <code>## How authentication works?</code>.</li>
<li><strong>Name the subject in the first sentence:</strong> Never open a section with "It," "This," "That," or "These" when the noun they refer to lives in the heading or a preceding chunk.</li>
<li><strong>Write concrete frontmatter descriptions:</strong> Every page's frontmatter <code>description</code> should be one clear sentence (or tight verb phrase) stating the job of the page, because retrieval pipelines use it as a summary blurb.</li>
</ul>
<table>
<thead>
<tr>
<th>Element</th>
<th>Before (ambiguous)</th>
<th>After (self-contained)</th>
</tr>
</thead>
<tbody><tr>
<td><strong>Procedural heading</strong></td>
<td><code>## Getting started</code></td>
<td><code>## Authenticate API requests with a bearer token</code></td>
</tr>
<tr>
<td><strong>Navigation heading</strong></td>
<td><code>## Next steps</code> (followed by bare links)</td>
<td>Keep <code>## Next steps</code>, with explicit labels and one-line descriptions: <code>- [Create a session](/docs/sessions/create): Open a session and store the session ID before you stream audio.</code></td>
</tr>
<tr>
<td><strong>Conceptual heading</strong></td>
<td><code>## Overview</code></td>
<td><code>## How session streaming works</code> (or <code>## When to use pre-recorded audio input</code>)</td>
</tr>
<tr>
<td><strong>Setup heading</strong></td>
<td><code>## Configuration</code></td>
<td><code>## Set the base URL and partner ID</code></td>
</tr>
<tr>
<td><strong>Section opener</strong></td>
<td><code>This lets you stream audio after you create it.</code></td>
<td><code>After you create a session, stream PCM audio over the WebSocket using the session ID returned in the create response.</code></td>
</tr>
<tr>
<td><strong>Link text</strong></td>
<td><code>Click here to learn more.</code></td>
<td><code>Read [Partner authentication](/docs/auth/partner) for token exchange and JWKS validation.</code></td>
</tr>
<tr>
<td><strong>Directional cues</strong></td>
<td><code>See the section below.</code> / <code>In the diagram above...</code></td>
<td><code>See [Streaming architecture](/docs/architecture/streaming).</code> / <code>In the preceding diagram, the client streams audio to the API.</code></td>
</tr>
</tbody></table>
<h3>Reusable section template</h3>
<p>Use this six-part pattern as your default skeleton for technical guides:</p>
<ul>
<li><strong>Explicit H2:</strong> State the exact task or concept in sentence case.</li>
<li><strong>Self-contained opener:</strong> Restate the task and name the primary object in sentence one.</li>
<li><strong>Inline prerequisites:</strong> List required tokens, IDs, or permissions in one line.</li>
<li><strong>Steps or contract:</strong> Provide numbered steps for procedures or parameter tables for contracts.</li>
<li><strong>Failure mode or constraint:</strong> State the primary error condition, rate limit, or state requirement.</li>
<li><strong>Explicit next link:</strong> Close with a descriptive link and a one-line outcome statement.</li>
</ul>
<blockquote>
<p><strong><mark>The Chunk Test:</mark></strong> <mark>Copy one H2 and the five lines immediately beneath it, paste them into a blank chat session with an LLM, and ask what product, task, and input IDs are required. If the model has to guess, rewrite the opening lines.</mark></p>
</blockquote>
<img src="https://cdn.hashnode.com/uploads/covers/6aa3a41bb290e89589f06fcf/d73d7d75-bdb5-485c-aa71-dac3857df242.png" alt="" style="display:block;margin:0 auto" />

<h2>Tabs, Accordions, and Mintlify Visibility</h2>
<p>I am a pro Mintlify user and it has a <strong><mark>component called</mark></strong> <code>&lt;Visibility for="agents"&gt;</code> which lets you preserve clean, progressive interfaces for human readers without starving LLM retrievers of secondary tabs or diagram logic. Treat the agent visibility block as a primary content surface, not an afterthought.</p>
<p>Apply these rules when building interactive components with Mintlify:</p>
<ul>
<li><strong>Use</strong> <code>&lt;Tabs&gt;</code> <strong>only for equivalent implementations:</strong> Every tab in a group should perform the exact same task in a different language or SDK.</li>
<li><strong>Place shared facts before the</strong> <code>&lt;Tabs&gt;</code> <strong>block:</strong> Put authentication rules, rate limits, and endpoint constraints above the tabs so both humans and agents read them first.</li>
<li><strong>Never hide mandatory steps inside an</strong> <code>&lt;Accordion&gt;</code><strong>:</strong> Reserve accordions for optional troubleshooting, edge-case FAQs, or legacy migration notes.</li>
<li><strong>Summarize language tabs for agents:</strong> Above a language tab group, add a short <code>&lt;Visibility for="agents"&gt;</code> note listing every supported language and confirming behavioral parity.</li>
<li><strong>Summarize decision tabs for agents:</strong> When using tabs to compare integration paths (by project type, team skills, or platform), add a <code>&lt;Visibility for="agents"&gt;</code> block summarizing each tab's key criteria and sibling links.</li>
<li><strong>Provide Mermaid twins for visual diagrams:</strong> Render light and dark SVG images for human readers, and keep the equivalent Mermaid source inside <code>&lt;Visibility for="agents"&gt;</code>.</li>
</ul>
<h2>Examples</h2>
<h3>Example A: Language tabs with agent summary</h3>
<p>Humans see one language tab at a time to keep the viewport clean. Agents read the visibility note first, see every supported SDK language, and select the snippet that matches the developer's repository.</p>
<pre><code class="language-mdx">&lt;Visibility for="agents"&gt;
**Language tabs (agents):** Equivalent code samples are available in: Python, TypeScript. Humans see one language at a time. Use the variant that matches the user's stack; behavior is the same across tabs.
&lt;/Visibility&gt;

&lt;Tabs&gt;
  &lt;Tab title="Python"&gt;
  ```python
  import os
  import requests

  response = requests.post(
      "[https://api.example.com/v1/sessions](https://api.example.com/v1/sessions)",
      headers={"Authorization": f"Bearer {os.environ['ACCESS_TOKEN']}"},
      json={"partner_id": "partner_abc", "provider_id": "provider-123"},
      timeout=10,
  )
  response.raise_for_status()
  print(response.json()["session_id"])
</code></pre>
<pre><code class="language-typescript">```typescript const response = await fetch("[https://api.example.com/v1/sessions\](https://api.example.com/v1/sessions)", { method: "POST", headers: { Authorization: `Bearer ${process.env.ACCESS_TOKEN}`, "Content-Type": "application/json", }, body: JSON.stringify({ partner_id: "partner_abc", provider_id: "provider-123", }), });

if (!response.ok) { throw new Error(Session creation failed: ${response.status}); }

const data = await response.json(); console.log(data.session_id);
</code></pre>
<pre><code class="language-plaintext">&lt;/Tab&gt;
&lt;/Tabs&gt;
</code></pre>
<h3>Example B: Decision tabs with agent summary</h3>
<p>When tabs separate architectural recommendations rather than identical code samples, summarize the decision matrix inside <code>&lt;Visibility for="agents"&gt;</code> so an agent evaluating options does not assume tab one is the only path.</p>
<pre><code class="language-mdx">&lt;Visibility for="agents"&gt;
**Tabs (agents):** Decision criteria for integration paths. Humans see one tab.

- **By project type:** Web SDK, headless SDK, or direct APIs; mobile SDK or APIs; backend REST and WebSocket endpoints.
- **By team skills:** Frontend-heavy, full-stack, and backend-heavy implementation recommendations.
- **By requirements:** UI ownership, speed to ship, custom UX controls, and interoperability needs.
&lt;/Visibility&gt;

&lt;Tabs&gt;
  &lt;Tab title="By Project Type"&gt;
    Use the Web SDK for browser apps that need prebuilt capture controls, or use backend REST and WebSocket APIs for server-to-server pipelines.
  &lt;/Tab&gt;
  &lt;Tab title="By Team Skills"&gt;
    Frontend teams ship fastest with the Web SDK. Backend teams with existing media pipelines should integrate directly over REST and WebSocket.
  &lt;/Tab&gt;
  &lt;Tab title="By Requirements"&gt;
    Choose the headless SDK when you require complete control over UI components while keeping built-in audio buffering and reconnect logic.
  &lt;/Tab&gt;
&lt;/Tabs&gt;
</code></pre>
<h3>Example C: Diagram twin for agents</h3>
<p>Human readers get high-contrast SVG diagrams tailored to light and dark themes, while agents parse the exact state flow from Mermaid without OCR errors.</p>
<pre><code class="language-mdx">{/* Humans: light/dark SVG images */}
&lt;img className="block dark:hidden" src="/images/streaming-flow-light.svg" alt="Session streaming sequence from login to end session" /&gt;
&lt;img className="hidden dark:block" src="/images/streaming-flow-dark.svg" alt="Session streaming sequence from login to end session" /&gt;

{/* Agents: Mermaid source kept readable */}
&lt;Visibility for="agents"&gt;
```mermaid
flowchart LR
  A[Login] --&gt; B[Create session]
  B --&gt; C[Open WebSocket]
  C --&gt; D[Stream audio]
  D --&gt; E[End session]
</code></pre>
<pre><code class="language-plaintext">
&gt; **The First-Tab Test:** Read only the first tab of every `&lt;Tabs&gt;` group on your page. If an agent reading that single branch would miss a platform constraint, authentication rule, or SDK requirement from tab two or three, move that fact above the tabs or summarize it inside `&lt;Visibility for="agents"&gt;`.

---

## Writing for OpenAPI and `llms.txt`

Coding agents rely on two structured maps to choose endpoints and pages before reading full guides: your OpenAPI specification and your `/llms.txt` index. Sharp descriptions in both files help agents pick the right method on the first try.

### OpenAPI description rules

* **Operation summary and description:** State the concrete outcome and when to call the endpoint, not generic filler like "Gets a resource."
* **Parameter descriptions:** State what the identifier is and where the caller obtained it.
* **Deprecations:** Name the replacement endpoint or parameter in the exact same sentence.
* **Error descriptions:** Name the specific condition that triggers the status code (such as an expired token or missing ID), not only the HTTP status phrase.

| OpenAPI field | Before (vague) | After (actionable) |
| --- | --- | --- |
| **Operation description** | `"description": "Gets session content."` | `"description": "Returns generated content for a session. Use the session ID from Create Session. Prefer GET /api/v1/sessions/{session_id}/content for new integrations."` |
| **Parameter description** | `"description": "The session id"` | `"description": "UUID for the session. Use the session_id returned from Create Session, or the UUID you supplied in that request."` |
| **Error description** | `"description": "Unauthorized"` | `"description": "Unauthorized. The access token is missing, expired, or invalid."` |

Here is how those rules look together in a production OpenAPI path definition:

```json
{
  "/api/v1/sessions/{session_id}/content": {
    "get": {
      "summary": "Get generated session content",
      "description": "Returns generated content for a completed session. Use the session_id returned by POST /api/v1/sessions. Replaces the deprecated /api/v1/transcripts endpoint.",
      "parameters": [
        {
          "name": "session_id",
          "in": "path",
          "required": true,
          "schema": { "type": "string", "format": "uuid" },
          "description": "UUID for the session. Use the session_id returned from Create Session, or the client-generated UUID supplied in that request."
        }
      ],
      "responses": {
        "200": {
          "description": "Generated structured content for the requested session."
        },
        "401": {
          "description": "Unauthorized. The bearer access token is missing, expired, or signed by an unrecognized key."
        }
      }
    }
  }
}
</code></pre>
<hr />
<h2>LLM.txt and page index blurb rules</h2>
<p>Treat every line in <code>/llms.txt</code> as a compact retrieval card. Follow a consistent pattern: <code>[Page title](url.md): one concrete job statement</code>. On Mintlify-powered sites, <mark>appending</mark> <code>.md</code> <mark>to any page URL automatically serves its Markdown version, giving AI agents a direct way to access the content without having to process the surrounding HTML.</mark></p>
<ul>
<li><strong>Start with a verb, object and constraint:</strong> Use action-oriented descriptions such as "Create...", "Compare..." or "Poll... until..." to make each page's purpose immediately clear.</li>
<li><strong>Keep each blurb between 150 and 200 characters:</strong> Put the most important keywords first, including workflow names, authentication methods and whether execution is synchronous or asynchronous.</li>
<li><strong>Add a site-level preamble:</strong> Include three to five bullets at the beginning of <code>llms.txt</code> to distinguish workflows that might otherwise look similar. For example, clearly differentiate two WebSocket paths that handle different audio formats so agents don't confuse their schemas.</li>
</ul>
<table>
<thead>
<tr>
<th><code>llms.txt</code> entry</th>
<th>Before (low signal)</th>
<th>After (high signal)</th>
</tr>
</thead>
<tbody><tr>
<td><strong>Workflow guide</strong></td>
<td><code>- [Overview](/docs/overview.md): Learn more about the platform</code></td>
<td><code>- [Create a session](/docs/how-to/create-session.md): Create a session from your UI, store session and note IDs, and choose interoperable create fields</code></td>
</tr>
<tr>
<td><strong>Auth reference</strong></td>
<td><code>- [Authentication](/docs/auth.md): Auth stuff</code></td>
<td><code>- [Partner authentication](/docs/how-to/partner-authentication.md): Compare Partner Token exchange, JWKS, and provider registration for API and SDK requests</code></td>
</tr>
</tbody></table>
<blockquote>
<p><strong>The</strong> <code>llms.txt</code> <strong>Skim Test:</strong> Read your <code>llms.txt</code> file with all page bodies hidden. Could someone pick the exact right page for five different integration tasks using only the titles and one-line blurbs? If two entries sound interchangeable, sharpen their verbs and constraints.</p>
</blockquote>
<h2>Complete, runnable code examples</h2>
<p>Agents struggle with half-examples. When a snippet omits imports, uses <code>foo</code> <mark>and</mark> <code>bar</code> <mark>placeholders,</mark> or skips error checks, an LLM fills in the gaps using statistical guesses from training data, which often introduces non-existent methods or outdated SDK syntax.</p>
<p>Enforce eight rules across every code block:</p>
<ol>
<li><strong>Always set a language tag</strong> on every fenced block (<code>typescript</code>, <code>python</code>, <code>bash</code>, <code>json</code>).</li>
<li><strong>Include complete imports or</strong> <code>require</code> <strong>statements</strong> at the top of the snippet.</li>
<li><strong>Use realistic parameter shapes and placeholder values</strong> (<code>org-123</code>, <code>partner_abc</code>, JWT-shaped strings), never <code>foo</code>, <code>bar</code>, or <code>x</code>.</li>
<li><strong>State the environment and base URL explicitly</strong> inside the snippet or the sentence immediately above it.</li>
<li><strong>Name the SDK package and version</strong> when the code depends on a specific release (or explicitly note "v2 client").</li>
<li><strong>Handle the primary failure branch</strong> in two or three lines (<code>401</code> or <code>409</code>) so agents do not invent error-handling classes.</li>
<li><strong>Label abbreviated pseudo-code explicitly</strong> above the fence and list every omitted piece before showing the snippet.</li>
<li><strong>Never use screenshots of code.</strong></li>
</ol>
<h3>Before: Incomplete snippet that forces agents to guess</h3>
<pre><code class="language-js">client.createSession({ patient: "x" })
// then stream
</code></pre>
<h3>After: Complete, runnable SDK example</h3>
<pre><code class="language-typescript">import { PlatformClient, PlatformApiError } from "@example/sdk"; // @example/sdk@2.4.0

const client = new PlatformClient({
  baseUrl: "https://api.example.com",
  accessToken: process.env.ACCESS_TOKEN!, // from Login / token exchange
});

try {
  const session = await client.sessions.create({
    partnerId: "partner_abc",
    providerId: "provider-123",
    encounterId: "enc-456",
  });

  console.log(session.sessionId); // store before you open the WebSocket
} catch (error) {
  if (error instanceof PlatformApiError &amp;&amp; error.status === 401) {
    throw new Error("Access token expired. Refresh the bearer token and retry.");
  }
  throw error;
}
</code></pre>
<h3>Complete REST reference example</h3>
<p>When documenting raw HTTP endpoints, include the full URL, explicit headers, realistic JSON payload, and status-code handling:</p>
<pre><code class="language-python">import os
import requests

BASE_URL = "https://api.example.com"
access_token = os.environ["ACCESS_TOKEN"]  # obtained from POST /v1/auth/token

response = requests.post(
    f"{BASE_URL}/v1/sessions",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
    },
    json={
        "partner_id": "partner_abc",
        "provider_id": "provider-123",
        "encounter_id": "enc-456",
        "audio_encoding": "pcm_s16le",
    },
    timeout=15,
)

if response.status_code == 401:
    raise RuntimeError("Unauthorized: refresh ACCESS_TOKEN before creating a session.")
if response.status_code == 409:
    raise RuntimeError("Conflict: encounter-456 already has an active session.")

response.raise_for_status()
session_id = response.json()["session_id"]
print(f"Created session: {session_id}")
</code></pre>
<h2>Style rules that double as AEO rules</h2>
<p>Clear, concise writing makes documentation easier to understand for both developers and AI agents. Apply these editorial rules as a final check before publishing:</p>
<table>
<thead>
<tr>
<th>Style rule</th>
<th>Before</th>
<th>After</th>
</tr>
</thead>
<tbody><tr>
<td><strong>Active voice, present tense</strong></td>
<td><code>A session ID will be returned by the server when the request finishes.</code></td>
<td><code>The server returns a session ID when the request succeeds.</code></td>
</tr>
<tr>
<td><strong>Name the object; avoid hedging unless conditional</strong></td>
<td><code>You may want to pass a timeout so it might not hang.</code></td>
<td><code>Set timeout=15 on every HTTP request to prevent hung worker threads.</code></td>
</tr>
<tr>
<td><strong>Cut subjective ease modifiers</strong></td>
<td><code>You can effortlessly configure webhooks in a few clicks.</code></td>
<td><code>Configure your webhook endpoint URL in **Settings &gt; Webhooks**.</code></td>
</tr>
<tr>
<td><strong>Avoid choppy AI staccato</strong></td>
<td><code>Create a token. Store the token. Open the socket. Send audio. Close the socket.</code></td>
<td><code>Exchange your credentials for a bearer token, open the WebSocket connection, and stream audio frames until the session ends.</code></td>
</tr>
<tr>
<td><strong>Cut throat-clearing openers</strong></td>
<td><code>The following section explains how to rotate signing keys.</code></td>
<td><code>Rotate signing keys every 90 days using the Key Management API.</code></td>
</tr>
<tr>
<td><strong>Bold exact UI labels; avoid icon-only cues</strong></td>
<td><code>Click the gear icon in the corner and hit save.</code></td>
<td><code>Open **Project Settings** and select **Save Changes**.</code></td>
</tr>
<tr>
<td><strong>Match components to intent</strong></td>
<td>Burying a mandatory API key step inside an FAQ dropdown.</td>
<td>Use <code>&lt;Steps&gt;</code> for required procedures, <code>&lt;Accordion&gt;</code> for optional FAQs, <code>&lt;Warning&gt;</code> for gating risks, and <code>&lt;Tip&gt;</code> for short workflow shortcuts.</td>
</tr>
</tbody></table>
<h2>Close the loop: style guide, skills, MCP, and plugins</h2>
<p>Writing self-contained, AI-readable documentation is an important first step, but good text alone doesn't guarantee that an IDE assistant will retrieve the right workflow when it needs to generate code. To make this work reliably, developer-experience teams <mark>need to combine strong technical writing with a complete AEO operating system.</mark></p>
<p>Here are the five components that make up that system:</p>
<ul>
<li><strong>A living style guide and CI lint rules:</strong> Define heading conventions, link standards and frontmatter requirements in your repository. This ensures that human writers and AI documentation agents follow the same standards when creating or updating content.</li>
<li><strong>Product agent skills (</strong><code>SKILL.md</code><strong>):</strong> Package multi-step integration workflows, endpoint selection rules and authentication requirements into installable skill files that coding agents can load before generating code.</li>
<li><strong>A documentation MCP server:</strong> Expose semantic search and OpenAPI schema inspection through the Model Context Protocol (MCP). This allows tools like Cursor, VS Code, Claude Code and Codex to retrieve verified documentation instead of relying on what the model already knows.</li>
<li><strong>Optional cookbook plugins and recipes:</strong> Provide short, task-specific recipes for common integration workflows, such as webhook signature verification and token refresh loops.</li>
<li><strong>Curated machine-readable indexes:</strong> Maintain <code>/llms.txt</code>, a skills index and a validated OpenAPI specification to give agents a reliable, structured entry point to your documentation.</li>
</ul>
<div data-node-type="callout">
<div data-node-type="callout-emoji">💡</div>
<div data-node-type="callout-text"><p>Write documentation that <strong>AI agents can retrieve and understand accurately,</strong> then give them a structured retrieval system that prioritises verified documentation over model memory.</p></div>
</div>

<img src="https://cdn.hashnode.com/uploads/covers/6aa3a41bb290e89589f06fcf/3937f12f-9b9d-4076-8cc3-c743806bd11c.png" alt="" style="display:block;margin:0 auto" />

<h2>Follow this checklist for AI-readable documentation</h2>
<ul>
<li><input disabled type="checkbox" /> Every H2 heading makes sense on its own.</li>
<li><input disabled type="checkbox" /> Section openers do not rely on vague pronouns like "it" or "this".</li>
<li><input disabled type="checkbox" /> Link text clearly describes its destination.</li>
<li><input disabled type="checkbox" /> No unique information exists only in the second or subsequent tabs.</li>
<li><input disabled type="checkbox" /> Language and decision tabs include summaries when using Mintlify Tabs.</li>
<li><input disabled type="checkbox" /> Diagrams have a text or Mermaid equivalent when provided as SVG or image files.</li>
<li><input disabled type="checkbox" /> OpenAPI descriptions explain the outcome and the source of each ID.</li>
<li><input disabled type="checkbox" /> llms.txt blurbs use verb-led job statements.</li>
<li><input disabled type="checkbox" /> Code samples include imports, realistic values, the base URL and the relevant version or package.</li>
<li><input disabled type="checkbox" /> Required steps are not hidden inside Accordions.</li>
<li><input disabled type="checkbox" /> Every page has a .md fetch path or an equivalent clean Markdown version.</li>
<li><input disabled type="checkbox" /> Agents have a documented path to skills, MCP and recipes for multi-step integrations.</li>
</ul>
<h2>Conclusion</h2>
<p>Designing documentation for coding agents doesn't mean sacrificing clarity, warmth or visual polish for human readers. It means <mark>making documentation understandable beyond its original visual interface.</mark> Use explicit headings, clear references, structured summaries and complete code examples. These improvements help human developers find information faster and give AI agents the context they need to generate accurate code.</p>
]]></content:encoded></item><item><title><![CDATA[How AI Is Changing Technical Writing and How You Can Prepare for What's Next]]></title><description><![CDATA[Explore how AI is changing technical writing and the skills you need to stay ahead. Learn AI tools, API documentation and documentation engineering.]]></description><link>https://tech-writing.hashnode.dev/how-ai-is-changing-technical-writing-and-how-you-can-prepare-for-what-s-next</link><guid isPermaLink="true">https://tech-writing.hashnode.dev/how-ai-is-changing-technical-writing-and-how-you-can-prepare-for-what-s-next</guid><category><![CDATA[technical writing]]></category><category><![CDATA[Artificial Intelligence]]></category><category><![CDATA[documentation]]></category><category><![CDATA[api]]></category><category><![CDATA[Career development ]]></category><dc:creator><![CDATA[Harshit Satyaseel]]></dc:creator><pubDate>Fri, 20 Nov 2026 09:20:32 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/covers/6aa3a41bb290e89589f06fcf/4ece1c64-38f9-4058-bd46-f27fa3496f35.jpg" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p>Technical writing as a profession is changing dramatically after the arrival of AI, and I don't think we're talking about just another new tool that technical writers need to learn.</p>
<p>I'm <strong>Harshit Satyaseel</strong>, author of <em><strong>The AI-Native Technical Writer</strong></em> and currently leading the documentation function at an AI company.</p>
<p><a class="embed-card" href="https://satyaseel.gumroad.com/l/ai-native-technical-writing">https://satyaseel.gumroad.com/l/ai-native-technical-writing</a></p>

<p>I've seen this change from very close, and I've experienced it myself. I started my career around seven years ago as a technical writer whose primary responsibility was writing documentation. I spent hours understanding requirements, working through JIRA tickets, writing guides and completing documentation tasks. That was what the job looked like for me back then.</p>
<blockquote>
<p><mark>But things have changed considerably.</mark></p>
</blockquote>
<p>Over the last few years, I've invested a lot of time learning AI tools, experimenting with prompts, working with coding agents and building automated documentation workflows. Today, my work goes far beyond writing and publishing pages. I'm involved in building documentation systems, automations and workflows that make documentation easier to create, validate and maintain.</p>
<p>And this experience has taught me something important: <strong>technical writers need to start preparing for a different kind of role.</strong></p>
<h2>How is the technical writing role changing?</h2>
<p>Traditionally, a technical writer would receive a PRD, understand the feature, write a guide, send it for review and publish it. Today, the expectations can be very different.</p>
<img src="https://cdn.hashnode.com/uploads/covers/6aa3a41bb290e89589f06fcf/5e8847b2-ace4-4fc6-909d-1ad8ccbfedfe.png" alt="" style="display:block;margin:0 auto" />

<p>Technical writers are increasingly expected to:</p>
<ul>
<li><strong>Read codebases</strong> and document features directly from their implementation.</li>
<li>Build and maintain <strong>OpenAPI specifications</strong>.</li>
<li>Define style guides, documentation standards and <strong>reusable variables</strong>.</li>
<li>Create <strong>AI agent skills</strong>, prompts and <strong>automated workflows</strong>.</li>
<li>Build <strong>CI/CD pipelines for documentation</strong> testing and publishing.</li>
<li>Automate documentation audits, link checks and quality validation.</li>
<li>Build <strong>workflows that detect code changes</strong> and help keep documentation updated.</li>
</ul>
<p>And the list goes on. We're moving from writing individual documentation pages to engineering the systems that create, validate and maintain them.</p>
<p>This doesn't mean traditional writing skills are becoming irrelevant. Clear communication, good information architecture and understanding developers still matter. But technical writers who combine these skills with AI, coding and automation will be better prepared for the opportunities ahead.</p>
<h2>Why I created the AI Technical Writer Career Kit</h2>
<p>Over the years, I've spent countless hours learning these skills, testing different approaches and figuring out how AI fits into real documentation workflows. I also realised that many technical writers want to make this transition but don't know where to begin. Some want to learn API documentation while others want to understand AI coding agents, write better prompts, automate repetitive tasks or prepare their resumes for new opportunities.</p>
<p>I wanted to bring these learning resources together into one practical career development kit at one place. That's how the <strong>AI Technical Writer Career Kit</strong> came together.</p>
<p>Here's what you'll get in the kit:</p>
<h3>1. AI Technical Writer Handbook</h3>
<p>A book that explains why the profession is changing, the concepts behind AI-native technical writing and how you can prepare for this transition, build automations and workflows.</p>
<h3>2. Hands-on API Documentation Course</h3>
<p>Learn a modern, AI-assisted approach to API documentation through 18 practical labs. You'll work with AI tools, prompts, automations and AI agents rather than just learning documentation theory.</p>
<h3>3. 30 High-Quality AI Prompts Guide</h3>
<p>A collection of 30 carefully developed prompts to help you give better instructions to AI coding agents and handle common technical writing tasks more effectively.</p>
<h3>4. PRD-to-Docs Agent Skill</h3>
<p>You'll still receive PRDs from product managers and engineering teams. This skill helps turn those requirements into consistent documentation by following the prompts, tools and standards defined in your repository.</p>
<h3>5. Technical Writer Resume Kit</h3>
<p>Learning new skills is important, but you also need to showcase them. This kit helps you present your experience, projects and practical capabilities through your resume and portfolio.</p>
<h3>6. Technical Writer Interview Guide</h3>
<p>Prepare for interviews and learn how to communicate your technical knowledge, experience and understanding of modern documentation practices.</p>
<div data-node-type="callout">
<div data-node-type="callout-emoji">💡</div>
<div data-node-type="callout-text"><p>Get the "The Complete AI Technical Writer Career Kit - Bundle" from the link below</p></div>
</div>
<p><a class="embed-card" href="https://satyaseel.gumroad.com/l/lugozs">https://satyaseel.gumroad.com/l/lugozs</a></p>

<h2>A little more than just learning materials</h2>
<p>I didn't want these resources to be six separate products that you purchase and figure out how to use on your own. I wanted them to work together, taking you from understanding the changing profession to learning practical skills and eventually showcasing those skills in your career.</p>
<blockquote>
<p><mark>The complete bundle is worth ₹5,564 and is available for ₹3,199.</mark></p>
</blockquote>
<p>And there's one more thing. <strong>Every purchase also includes a free one-on-one session with me.</strong></p>
<p><a class="embed-card" href="https://topmate.io/harshit_satyaseel">https://topmate.io/harshit_satyaseel</a></p>

<p><mark>I want to make sure you get value from these resources. We can discuss your learning goals, walk through the materials and talk about how you can apply what you've learned to your own technical writing career.</mark></p>
<h2>The next step in your technical writing career</h2>
<p>If there's one thing I'd like fellow technical writers to take away from my experience, it's this: you don't have to abandon traditional technical writing to grow. You need to build on what you already know.</p>
<p>Start understanding codebases. Learn API documentation, experiment with AI agents, build automations, find ways to make your documentation workflows more reliable and AEO friendly.</p>
<p>You don't have to learn everything overnight, but you should start somewhere. I've put considerable time and practical experience into creating this Career Kit, and I hope it helps other technical writers navigate the same transition.</p>
<p>Let's build the next generation of technical writing ready for the shift.</p>
]]></content:encoded></item><item><title><![CDATA[30 Documentation Prompts for AI Coding Agents: A Practical Guide for Technical Writers]]></title><description><![CDATA[I distilled 3.5 years of prompting experience into 30 practical prompts designed to help technical writers use AI coding agents across the documentation…]]></description><link>https://tech-writing.hashnode.dev/30-documentation-prompts-for-ai-coding-agents-a-practical-guide-for-technical-writers</link><guid isPermaLink="true">https://tech-writing.hashnode.dev/30-documentation-prompts-for-ai-coding-agents-a-practical-guide-for-technical-writers</guid><category><![CDATA[prompting]]></category><category><![CDATA[Technical writing ]]></category><category><![CDATA[tips and tricks]]></category><category><![CDATA[engineering]]></category><category><![CDATA[AI]]></category><dc:creator><![CDATA[Harshit Satyaseel]]></dc:creator><pubDate>Fri, 20 Nov 2026 07:25:28 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/covers/6aa3a41bb290e89589f06fcf/79865b83-c97a-4f2f-8d3a-cdcee1d97e07.png" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p>I use Cursor for my documentation work almost every day. Over the past two years, I have given it thousands of prompts, gradually refining the way I work with AI. Out of curiosity, I asked Cursor to analyse my agent history and estimate my usage. The numbers were surprising: around <strong>25</strong> to <strong>28</strong> prompts per day, across more than <strong>700</strong> coding sessions. That's an estimated <strong>18,000 to 20,500 prompts</strong> over two years, and this wasn't just about writing documentation. My work with Cursor covered much more:</p>
<ul>
<li>Research and content review: Researching technical topics, reviewing AI-generated content and correcting inaccurate or incomplete output.</li>
<li>Systems and automation: Building documentation systems, automations and AI agents, then running and testing them.</li>
<li>Testing and evaluation: Setting up regression tests and evaluation workflows to check the quality and reliability of AI-generated output.</li>
<li>Learning resources: Writing cookbooks, tutorials and implementation guides. - Partner enablement: Building demo applications for partners and testing their integrations.</li>
<li>Development workflows: Working directly in code repositories, reviewing code and making documentation-related changes.</li>
</ul>
<p>I'm sharing these numbers for a reason. Working with AI this extensively, across so many different tasks, gave me a <strong>clear view of my prompting habits</strong>, what worked, what didn't and where I could improve. Over time, I identified recurring patterns and turned those learnings into effective, reusable prompts. This article explains what I learned and how I built that collection.</p>
<div data-node-type="callout">
<div data-node-type="callout-emoji">💡</div>
<div data-node-type="callout-text"><p>Get my prompt guide from the following link.</p></div>
</div>
<p><a class="embed-card" href="https://satyaseel.gumroad.com/l/kmifnf">https://satyaseel.gumroad.com/l/kmifnf</a></p>

<h2>How my documentation sessions used to start</h2>
<p>For a long time, almost every documentation session followed the same routine. I used to open the repository, start a new chat with the AI agent and repeat the same instructions: check the source of truth, tell it not to invent API fields and only modify the files I've specified.</p>
<p>The problem wasn't that the agent was ignoring my instructions. It was that every new session started without the context of my previous conversations. The corrections and rules I'd established yesterday weren't automatically carried over to today's session. After repeating these instructions for weeks, I started looking at the pattern differently.</p>
<p>Instead of treating each correction as a one-off instruction, I wanted to understand which rules I kept repeating and why. So I went back through my Cursor history and <strong><mark>identified a set of recurring tasks and instructions</mark></strong><mark>:</mark></p>
<img src="https://cdn.hashnode.com/uploads/covers/6aa3a41bb290e89589f06fcf/c4f3c5b7-c159-4a7d-9972-efc2632c2881.png" alt="" style="display:block;margin:0 auto" />

<ul>
<li><strong>Verify before writing</strong>: Check the API specification, source code or other authoritative source before making documentation changes.</li>
<li><strong>Protect API accuracy:</strong> Never invent API fields, parameters, response properties or behaviour that isn't supported by the source.</li>
<li><strong>Understand the page type:</strong> Identify whether the task involves an API reference, tutorial, how-to guide or conceptual explanation before writing.</li>
<li><strong>Keep instructions focused</strong>: Make each how-to guide solve one specific problem rather than combining unrelated workflows.</li>
<li><strong>Maintain the documentation style and follow the style guide:</strong> Rewrite content to match the established writing style without introducing unsupported claims.</li>
<li><strong>Review before editing:</strong> Critique the existing content first, identify issues and then propose changes.</li>
<li><strong>Control the scope:</strong> Specify exactly which files the agent can inspect or modify.</li>
<li><strong>Protect Git operations:</strong> Ask for confirmation before destructive Git actions.</li>
<li><strong>Validate before committing:</strong> Run the required checks and review the changes before every commit.</li>
<li><strong>Make corrections reusable:</strong> Turn recurring feedback into explicit rules so the same mistakes don't keep happening.</li>
</ul>
<blockquote>
<p>I realised that most of these weren't isolated prompts. They were repeatable instructions that could be organised into a system and reused across sessions.</p>
</blockquote>
<h2>How I fixed it</h2>
<p>I fixed this problem in <strong>three small steps</strong>. First, I kept every prompt that worked well; then I wrote down each correction I made, along with the reason. Finally, I grouped everything by the job it did and cut the duplicates. I only learned later that this is unusual.</p>
<div data-node-type="callout">
<div data-node-type="callout-emoji">💡</div>
<div data-node-type="callout-text"><p><mark class="bg-highlight text-highlight-foreground">A 2025 survey of 74 software professionals asked how often they reuse prompts. Only 11% said they reuse them regularly, and 46% said they never do</mark></p></div>
</div>

<p>Most people start from a blank box every time they start a node session with AI coding tools. I had been doing the opposite, first by accident and later on purpose. That habit is the reason that I was able to <strong>create a small library of prompts.</strong></p>
<div data-node-type="callout">
<div data-node-type="callout-emoji">💡</div>
<div data-node-type="callout-text"><p>Looking for a course on AI Native API documentation? Check my course and book</p></div>
</div>
<p><a class="embed-card" href="https://satyaseel.gumroad.com/l/lugozs">https://satyaseel.gumroad.com/l/lugozs</a></p>

<h2>Why thirty prompts only</h2>
<p>Most documentation work follows a fairly predictable set of workflows. You write how-to guides, conceptual pages, API references, release notes and changelogs. You also review existing content, audit documentation, fix broken links and maintain consistent terminology.</p>
<blockquote>
<p>The specific product may change, but the underlying tasks remain largely the same. AI agents also tend to make the same mistakes across these workflows.</p>
</blockquote>
<p>They invent technical details, modify files outside the requested scope, miss important context and sometimes present assumptions as facts. Collecting hundreds of one-off prompts doesn't solve this problem. You end up with a large prompt library but still have to figure out which instruction to use, when to use it and how to adapt it. What you need is a <strong>smaller, well-organised set of reusable instructions</strong> that covers the most common documentation workflows and addresses recurring agent failures.</p>
<p>That's why I condensed two years of my hands-on experience into 30 reusable prompts. The goal wasn't to capture every instruction I've ever written but to identify the patterns that consistently improved the quality, accuracy and reliability of my documentation work.</p>
<p>Think of it this way: out of an estimated 18,000 to 20,500 prompts I sent, I selected <strong>30 patterns that made the most sense to me</strong>.</p>
<img src="https://cdn.hashnode.com/uploads/covers/6aa3a41bb290e89589f06fcf/0dad2c35-2a52-442c-b52b-92dca33baad2.png" alt="" style="display:block;margin:0 auto" />

<p>That ratio sounds extreme, but most of my doc prompts were the same few jobs on different files.</p>
<h2>The flow: how 30 prompts fit together</h2>
<p>The 30 prompts are not a pile of random stuff; instead, they follow t<strong>he order of a real docs job</strong> an AI-native tech writer does every single day. The easiest way to see this is in three phases: prepare, do the work and ship.</p>
<ul>
<li><strong>Phase 1: Prepare the agent:</strong> Before the agent writes anything, it needs to understand your documentation environment and repo rules. It needs to read your writing rules, style guide and relevant skills, map the repository and identify the type of task it needs to perform. So your prompt must define which files it can access or modify, turn recurring instructions into reusable rule and skill files and document the terminology and technical constraints it must follow. This phase doesn't produce documentation pages. It establishes the context, rules and boundaries that every subsequent task depends on.</li>
</ul>
<img src="https://cdn.hashnode.com/uploads/covers/6aa3a41bb290e89589f06fcf/542ee735-fff0-4603-9cd9-d7e7b352f9af.png" alt="" style="display:block;margin:0 auto" />

<ul>
<li><strong>Phase 2: Create and review documentation:</strong> Your prompt must tell the agent to start any task with verified source material and follow the structure and writing style of the surrounding documentation. It should also define checks for terminology, links, consistency and writing style, then verify technical claims against the relevant specifications. Because these checks use the terminology rules and technical constraints established in Phase 1, they can identify actual issues rather than simply relying on the agent's own interpretation.</li>
<li><strong>Phase 3: Prepare and ship changes:</strong> This phase focuses on preparing changelog entries, writing release notes and updating documentation when product features change or become deprecated. It also connects the product repository with the documentation repository through a structured documentation brief and a pre-commit checklist. This helps ensure that documentation changes are captured, reviewed and validated as part of the development workflow.</li>
</ul>
<p><mark>Automation comes last for a reason. First, establish a process, run it manually and make sure it produces reliable results.</mark> Only then should you automate it.</p>
<h2><strong>What makes a single prompt work</strong></h2>
<p>In my curated guide of 30 highly effective prompts for technical writers, every prompt follows the same structure. Each part has a specific purpose, and together they help the AI agent produce more accurate, consistent and reliable results. Every prompt starts by <strong>defining the agent's role</strong> and the <strong>type of task</strong> it needs to perform. It then identifies the <strong>approved sources of information</strong> that serve as the ground truth.</p>
<p>Next come the constraints, including which files are in scope, what actions are allowed and where human confirmation is required. The prompt also defines the expected output format and ends with a clear completion check, along with explicit instructions about what the agent must never assume or invent.</p>
<p>One important element is the <mark>done-when check</mark>. It gives you a <strong><mark>measurable way to verify whether the task is complete.</mark></strong> For example, suppose an API specification defines 15 fields. The API reference prompt asks the agent to report two counts: the number of fields in the specification and the number of fields documented. If the counts don't match, you immediately know that something needs investigation.</p>
<p>Two elements make the biggest difference: <strong>verified source material</strong> and the <strong>permission to return BLOCKED.</strong> Without these, an agent may still generate a complete-looking page, even when it lacks the information needed to do the job correctly. By explicitly defining its sources and allowing it to report BLOCKED when information is missing, you prevent it from <strong>filling gaps with assumptions</strong>.</p>
<p>Instead, it brings unknowns back to you as specific questions that can be resolved before the work continues.</p>
<h2>The feedback loop that makes the system improve</h2>
<p>One of the most valuable prompts in my curated collection is the one I use after <strong>correcting the agent's work</strong>. Whenever I find and fix a mistake, I ask the agent to document what happened. It records what it originally did, what I changed, why the original output was incorrect and what validation check it should perform to avoid making the same mistake again. I then review that learning and decide whether it should become part of an existing rule or skill file.</p>
<p>If it is relevant to future tasks, I add it to the agent's reusable context. This creates a continuous feedback loop that feeds directly into Phase 1. The agent doesn't just complete tasks. Its working rules evolve based on the corrections and lessons gathered from previous tasks.</p>
<p><strong>The goal is simple</strong>: the agent should carry forward the judgment you've already developed, instead of making you repeat the same corrections every day.</p>
<h2>How to get started</h2>
<p>There are five moments when I typically reach for one of these prompts:</p>
<ul>
<li>At the start of a task: Prepare the agent and establish the context it needs.</li>
<li>When the agent starts drifting: Bring it back to the defined scope and instructions.</li>
<li>Before rewriting content: Review the source material and existing documentation first.</li>
<li>Before committing changes: Validate the output and check the affected files.</li>
<li>After correcting a mistake: Capture the learning and update the reusable rules.</li>
</ul>
<h2>Conclusion</h2>
<p>For any AI to produce reliable results, you need to provide the best context. If you provide partial information, the agent may fill in the missing details with assumptions. Always provide a specific file path, API specification, ticket or other relevant reference. Clear inputs lead to more reliable output and leave less room for guesswork.</p>
<p>Ultimately, working effectively with AI isn’t about how many prompts you write. It’s about how well you structure your instructions, define boundaries and build on previous learnings.</p>
<p>If you maintain developer documentation using Cursor or any other coding agent, you don’t need thousands of prompts. You need a small, carefully designed collection of instructions that you can trust, reuse and improve over time.</p>
]]></content:encoded></item><item><title><![CDATA[OpenAPI Documentation Platforms Compared: Mintlify, GitBook, Velu Docs and Document360]]></title><description><![CDATA[Compare Mintlify, GitBook, Velu and Document360 on one OpenAPI 3.1 spec: API reference output, update workflow, AI tool access and pricing.]]></description><link>https://tech-writing.hashnode.dev/openapi-documentation-platforms-compared-mintlify-gitbook-velu-docs-and-document360</link><guid isPermaLink="true">https://tech-writing.hashnode.dev/openapi-documentation-platforms-compared-mintlify-gitbook-velu-docs-and-document360</guid><category><![CDATA[api documentation]]></category><category><![CDATA[OpenApi]]></category><category><![CDATA[technical writing]]></category><category><![CDATA[documentation]]></category><dc:creator><![CDATA[Harshit Satyaseel]]></dc:creator><pubDate>Thu, 19 Nov 2026 10:24:17 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/covers/6aa3a41bb290e89589f06fcf/c5eb9da4-93d1-4755-a3b6-4e43439afbf1.png" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p>There is no shortage of documentation platforms today. <a href="https://mintlify.com">Mintlify</a>, <a href="https://www.gitbook.com">GitBook</a>, <a href="https://readme.com">ReadMe</a>, <a href="https://stoplight.io">Stoplight</a>, <a href="https://buildwithfern.com">Fern</a>, <a href="https://document360.com">Document360</a>, <a href="https://www.veludocs.com">Velu</a> and several others all promise to help teams publish better developer documentation.</p>
<div data-node-type="callout">
<div data-node-type="callout-emoji">💡</div>
<div data-node-type="callout-text"><p>Looking to build a career in technical writing? Connect with me for a free 1:1 consultation or get my course and book on AI Native technical writing.</p></div>
</div>
<p><a class="embed-card" href="https://topmate.io/harshit_satyaseel">https://topmate.io/harshit_satyaseel</a></p>

<p>At first glance, many of these products seem to do the same things. They can turn an OpenAPI file into endpoint pages, display request and response schemas and give developers a way to try an API. But the differences become clearer when you look beyond the feature list. For example,</p>
<ul>
<li>How much work does it take to get an API reference published?</li>
<li>What happens when the API changes?</li>
<li>Can the documentation stay in sync with the source specification?</li>
<li>What does the experience look like for the developer who needs to use the API?</li>
</ul>
<p>There is another question that matters more now than it did a few years ago:</p>
<blockquote>
<p><mark>How well does the documentation work with AI coding tools?</mark></p>
</blockquote>
<p>Many of the developers I talk to increasingly use tools such as Cursor and Claude Code to understand unfamiliar code, explore APIs and build integrations. They expect these tools to <strong>find relevant documentation</strong> and use it as context while they work. An API documentation platform <strong>therefore needs to serve two audiences</strong>:</p>
<ul>
<li>The developer reading the reference</li>
<li>The coding assistant retrieving information from it.</li>
</ul>
<p>Features such as <strong>Model Context Protocol (MCP)</strong> support and machine-readable documentation can help. But an MCP connection alone does not make documentation useful to an AI assistant. The underlying API specification still needs to be accurate, the reference needs to explain the API clearly, and the retrieval experience needs to return the right information.</p>
<p>That is the problem I wanted to explore.</p>
<p>I compared <strong>Mintlify, GitBook, Velu Docs and Document360</strong> using the same fictional Notes API contract. The comparison covers how each platform handles OpenAPI, what it produces for developers, how teams can maintain the reference and how the platforms fit into AI-assisted development. Pricing is part of it too, because a tool can have an impressive feature set and still be difficult to justify for a small API team.</p>
<blockquote>
<p><mark>This is not a general review of documentation platforms. The focus is API documentation: the path from an OpenAPI specification to a published, maintainable reference that developers can actually use.</mark></p>
</blockquote>
<h2>What makes a good API documentation platform?</h2>
<p>An API reference is not useful just because it lists every endpoint. A developer needs to understand what an operation does, what information to send, how authentication works and what to expect in return. They also need to know whether the example on the page reflects the current API.</p>
<p>That means we need to evaluate more than the appearance of the generated pages. The comparison looks at the following parts of each platform:</p>
<ul>
<li><strong>OpenAPI support:</strong> Can the platform import an existing OpenAPI or Swagger specification? Does it support the formats the team already produces?</li>
<li><strong>Generated reference:</strong> Does it create useful endpoint pages with methods, paths, descriptions, parameters, request bodies, responses and schemas?</li>
<li><strong>Authentication and examples:</strong> Are security schemes represented clearly? Can developers understand the request and response without having to decode the specification themselves?</li>
<li><strong>Interactive testing:</strong> Can a developer try an operation from the reference, and what configuration is needed to make that work?</li>
<li><strong>Navigation and models:</strong> Are operations grouped in a useful way? Can developers find shared schemas without hunting through individual endpoints?</li>
<li><strong>Maintenance workflow:</strong> Can the team update the reference through Git, a URL, a CLI or a repeatable CI/CD process?</li>
<li><strong>AI access:</strong> Can compatible coding assistants retrieve the documentation through MCP or another machine-readable interface?</li>
<li><strong>Cost:</strong> What does a team need to pay to get the API documentation workflow it actually needs? General knowledge-base management, blog publishing, support portals and ticketing are outside the scope. Those may matter when choosing a wider documentation system, but they do not tell us how well a platform handles an API contract.</li>
</ul>
<div data-node-type="callout">
<div data-node-type="callout-emoji">💡</div>
<div data-node-type="callout-text"><p>Get my Full AI Native technical writer kit here:</p></div>
</div>
<p><a class="embed-card" href="https://satyaseel.gumroad.com/l/lugozs">https://satyaseel.gumroad.com/l/lugozs</a></p>

<h2>The test: one OpenAPI contract across four platforms</h2>
<p>To keep the comparison consistent and fair, I used the same OpenAPI 3.1 specification for a small Notes API which I created. The contract described four operations:</p>
<table>
<thead>
<tr>
<th>Operation</th>
<th>Purpose</th>
</tr>
</thead>
<tbody><tr>
<td><code>POST /auth/token</code></td>
<td>Create an access token</td>
</tr>
<tr>
<td><code>POST /sessions</code></td>
<td>Create a session</td>
</tr>
<tr>
<td><code>POST /sessions/{session_id}/end</code></td>
<td>End a session</td>
</tr>
<tr>
<td><code>GET /sessions/{session_id}/note</code></td>
<td>Retrieve a note</td>
</tr>
</tbody></table>
<img src="https://cdn.hashnode.com/uploads/covers/6aa3a41bb290e89589f06fcf/905b039e-89ef-4915-bd41-bf4ac818e338.png" alt="" style="display:block;margin:0 auto" />

<p>The contract exists in both <code>openapi.yaml</code> and <code>openapi.json</code>. They represent the same API, but using both formats makes it possible to see whether a platform fits a team's existing build output or expects a particular file format.</p>
<p>For each platform, the available workflow was followed to connect the specification and generate the reference. The rendered pages were then checked against the source contract for authentication requirements, parameters, request fields, schemas and response details. The interactive testing experience and the steps needed to publish updates were part of the check as well.</p>
<blockquote>
<p>The amount of hands-on evidence is not the same for all four platforms, so the distinction matters:</p>
<ul>
<li><strong>Mintlify:</strong> Tested in a local project, with screenshots of the guides and a complete Create Session API page.</li>
<li><strong>GitBook:</strong> The API reference was generated and published, with the Authentication, Sessions, Notes and Models sections captured.</li>
<li><strong>Velu Docs:</strong> A local project was connected to the OpenAPI file through <code>velu.json</code>, and the generated endpoint pages were tested along with the guide workflow.</li>
<li><strong>Document360:</strong> The same self-serve test could not be completed, so no generated endpoint pages were captured from a project of my own. The findings in that section are based on Document360's published product documentation. I will call out those differences rather than present every feature as something I personally tested. A feature described in vendor documentation is useful evidence, but it is not the same as a hands-on result.</li>
</ul>
</blockquote>
<h2>Mintlify: A Git-based workflow for teams that maintain their API contract in code</h2>
<p>I am a pro Mintlify user from the <strong>past 2 years</strong>, so I know this end-to-end. But I will explain this as some one who is new to this.<br /><br />Mintlify follows a docs-as-code model. The OpenAPI file lives in the documentation repository, and the site configuration points to that file. The reference is generated as part of the documentation project rather than managed as a separate API product.</p>
<p>For the Notes API, the project needs the specification and an API Reference tab in <code>docs.json</code>:</p>
<pre><code class="language-json">{
  "tab": "API Reference",
  "openapi": "openapi.json"
}
</code></pre>
<p>The Mintlify CLI then validates the project and starts a local preview:</p>
<pre><code class="language-bash">npm i -g mint
mint validate
mint dev
</code></pre>
<p>The setup was straightforward once the documentation project was in place. There was no separate API workspace to configure. The OpenAPI file remained the source for the generated reference.</p>
<img src="https://cdn.hashnode.com/uploads/covers/6aa3a41bb290e89589f06fcf/a45e6125-1ff3-474f-925e-6eeb5acbcd64.png" alt="" style="display:block;margin:0 auto" />

<h3>The generated reference</h3>
<p>The Create Session page displayed the HTTP method and path, operation description, bearer-token authorization, request-body fields, required markers, enum values and nested metadata. It also showed response fields, a cURL request and an example JSON response in the side panel.</p>
<p>The page used a three-column layout: navigation on the left, the operation reference in the middle and request or response examples alongside it. The OpenAPI tags grouped operations under Authentication, Sessions and Notes.</p>
<p>In Mintlify you can directly <strong>try</strong> any API endpoint from it's UI, which in my opinion is really handy. It's useful because a developer can move from reading the operation to testing it without switching to a separate tool.</p>
<p>Mintlify does a really good job as the rendered contract stayed close to the OpenAPI source. That is the main strength of the workflow and this tool: the reference is generated from a file that can remain under version control and you can build an automation on top of it the way I wrote in <a href="https://levelup.gitconnected.com/building-self-maintaining-api-documentation-with-ai-agents-046a2f395fc8?sharedUserId=hsatyaseel">this blog</a>.</p>
<div data-node-type="callout">
<div data-node-type="callout-emoji">💡</div>
<div data-node-type="callout-text"><p><strong>Get my latest API documentation course.</strong> Learn how to use AI to produce reliable API documentation, and build agents that keep your docs up to date on their own.</p></div>
</div>
<p><a class="embed-card" href="https://satyaseel.gumroad.com/l/tlapqh">https://satyaseel.gumroad.com/l/tlapqh</a></p>

<h3>Where the workflow fits</h3>
<p>The biggest advantage of Mintlify is the connection between the API specification and the publishing process. If the API team updates the OpenAPI file in Git, the documentation project can pick up the change through its normal build and publishing workflow. An automated watcher or agent can update the file, validate the project and trigger a build. The team does not need to repeat a manual upload every time the contract changes.</p>
<blockquote>
<p><mark>This approach is a natural fit for teams that already review API changes through pull requests and want documentation updates to follow the same process.</mark></p>
</blockquote>
<p>The generated page also included the reference details I would expect developers to need: authentication, required fields, nested objects, response examples and interactive testing.</p>
<h3>What to consider</h3>
<p>In this test, Mintlify was set up as a documentation project, which means working with the repository structure, a configuration file and the CLI. That is a reasonable trade-off for a team already using Git, but it is more setup than uploading a file into a hosted interface.</p>
<p>Mintlify is not Git-only, though. It also offers a web editor that commits changes back to the repository, so writers who do not work in Git can edit in the browser. That route was not part of this test, which started from a local project.</p>
<p>It is also important to separate the API reference workflow from the wider Mintlify product. The API playground is not limited to the expensive plan. Mintlify's Free plan includes an API playground, so a team should not assume it needs Pro just to publish an interactive API reference.</p>
<blockquote>
<p>Mintlify makes the most sense <strong>when the repository is already the center of the documentation</strong> workflow and the team wants the API reference maintained alongside the code, with a browser editor available for contributors who prefer it.</p>
</blockquote>
<h2>GitBook: The quickest way to generate the API reference from UI</h2>
<p>Mintlify and GitBook can both be driven from a repository and from a browser. The two tests simply started at different points. Where Mintlify began as a local project, GitBook began in the hosted product, where the specification is imported and the result is published. No separate project had to be set up before the generated API reference appeared.</p>
<p>The workflow was short:</p>
<ol>
<li>Open the OpenAPI area in GitBook.</li>
<li>Choose the option to add a specification.</li>
<li>Upload <code>openapi.yaml</code>.</li>
<li>Add an OpenAPI Reference section for that specification.</li>
<li>Publish the space.</li>
</ol>
<p><mark>GitBook generated the reference pages from the uploaded file. Of the four workflows evaluated, this was the</mark> <strong><mark>quickest hosted integration</mark></strong>.</p>
<h3>The generated reference</h3>
<p>GitBook created Authentication, Sessions, Notes and Models sections from the Notes API contract.</p>
<p>The reference included the token operation, the Create Session operation with its bearer authentication and request fields, and the Get Note operation with its <code>session_id</code> path parameter. It also created a Models section containing shared schemas such as <code>TokenRequest</code>, <code>Session</code>, <code>Note</code> and <code>Error</code>.</p>
<p>The pages included a Test it control. GitBook also provided a <strong>way to download the OpenAPI specification from the sidebar,</strong> so the source contract was easy to retrieve.</p>
<p>The generated pages matched the parts of the Notes API contract that were checked. The Models section was particularly useful because shared types had a visible home rather than appearing only as references inside individual endpoint pages.</p>
<img src="https://cdn.hashnode.com/uploads/covers/6aa3a41bb290e89589f06fcf/7f9905a7-88e5-4b64-add1-ab7cd76febd9.png" alt="" style="display:block;margin:0 auto" />

<h3>Where the workflow fits</h3>
<p>GitBook's main strength in this test was how quickly a file became a published reference. For a team evaluating API documentation platforms, uploading a YAML file is a simple way to get started. The generated output included operations, shared models, interactive testing and access to the original specification.</p>
<p>The hosted import does not mean a team has to rely on manual uploads forever. GitBook supports a <strong>docs-as-code approach as well.</strong> Git Sync works in both directions with GitHub and GitLab, so content can be edited in the app or in a repository, and GitBook lists it on every plan, including Free.</p>
<p>For the specification itself, GitBook also supports URL-based and CLI publishing options. Those options give teams a path to automate updates after the initial setup.</p>
<h3>What to consider</h3>
<p>The workflow that was tested was upload-first, so the Git, URL and CLI routes were not exercised. If your API specification lives in a <strong>monorepo and changes as part of every release,</strong> you will need to connect that process to GitBook through its supported sync or publishing options and confirm how the update behaves with your own file.</p>
<p>That is not a problem with the generated reference itself. It is a question of where the team wants to start. In this test, Mintlify began from the repository and GitBook began from the browser, but each platform offers the other route as well.</p>
<blockquote>
<p>GitBook is a strong option when the priority is to turn an existing OpenAPI file into a <strong>browsable API reference</strong> with very little initial setup.</p>
</blockquote>
<h2>Velu Docs: A configuration-led workflow with built-in AI outputs and a free plan</h2>
<p>Velu and Mintlify are too similar and uses a configuration-led workflow that will feel familiar to teams that have worked with docs-as-code tools. You add the OpenAPI file to the project and point the API Reference tab in <code>velu.json</code> to it.</p>
<p>The project configuration was set up as follows:</p>
<pre><code class="language-json">{
  "tab": "API Reference",
  "openapi": "/openapi.json"
}
</code></pre>
<p>The Velu CLI initializes and validates the project:</p>
<pre><code class="language-bash">npx @veluai/velu init notes-api-docs
npx @veluai/velu validate .
npx @veluai/velu dev
</code></pre>
<p>Velu follows a spec-driven workflow where it reads the OpenAPI file, groups operations by tag, creates a page for each operation and provides a <strong>Try It playground feature as well.</strong></p>
<img src="https://cdn.hashnode.com/uploads/covers/6aa3a41bb290e89589f06fcf/a15ccc01-2635-457d-9f87-cc37f66c5e13.png" alt="" style="display:block;margin:0 auto" />

<h3>How Velu compares</h3>
<p>Generating endpoint pages is not what sets Velu apart. Mintlify and GitBook also generate API references from OpenAPI. Also, making documentation available to AI tools does not set it apart either as all four platforms document some form of AI capability.<br /><br />Mintlify and GitBook each provide an MCP server for the documentation they host, and Document360 documents an MCP connector. Velu describes MCP and machine-readable outputs <strong>as part of its platform</strong>, which puts it in the same category as the others, not ahead of them.</p>
<p>The closest comparison is Mintlify. Both use a configuration file that points to the OpenAPI file, both have a CLI for validation and local preview, and both fit a Git-oriented workflow. The useful questions are <strong>how the generated pages and AI outputs compare</strong> with Mintlify's on the team's own specification, and what each plan costs for that workflow. Both platforms offer the OpenAPI, CLI and MCP workflow on a free plan. <mark>Velu's paid plans cost $0, $9 and $49 per month, while Mintlify Pro costs $450 per month and adds features such as unlimited editors, an assistant, a writing agent, Autopilot and preview deployments.</mark></p>
<h3>Where the workflow fits</h3>
<p>The configuration-based integration can fit a Git-oriented workflow. An automation process can update the OpenAPI file and run the documentation build without requiring someone to upload a new specification manually.</p>
<p>Velu's MCP and machine-readable outputs deserve the same retrieval test as every other platform here. The documentation describes them, but this comparison did not measure how well an assistant finds the right page on a Velu site compared with Mintlify or GitBook.</p>
<h2>What to consider</h2>
<p>The file format needs a check as I used <code>openapi.json</code>. A team that produces only YAML should confirm that Velu reads its file correctly before committing to the workflow, and should not add a conversion step to the build on the strength of a starter example.</p>
<p><mark>Pricing is where Velu</mark> <strong><mark>stands out</mark></strong><mark>, but the paid plans are not like-for-like with Mintlify Pro. Velu's free plan covers the OpenAPI, CLI and MCP workflow, and its paid plans start at $9 per month.</mark></p>
<blockquote>
<p>Because AI access does not separate Velu from the other platforms, the decision <strong>rests on how its generated pages compare with Mintlify’s on the team’s own specification</strong> and on the cost of the plan that includes them.</p>
</blockquote>
<h2>Document360: A dedicated API workspace within a wider documentation portal</h2>
<p>Document360 takes a different approach from the other platforms in this comparison. Its API documentation feature is managed in a dedicated workspace within the product, separate from the standard knowledge-base content.</p>
<p>The same hands-on test that was run with Mintlify and GitBook could not be completed for Document360 as <strong>the product's access path was demo-led,</strong> so no generated endpoint pages were captured from a Notes API project which is hurdle in my opinion.</p>
<h3>What Document360 supports</h3>
<p>This section is based on Document360's published documentation, not on a hands-on test.</p>
<p>Document360's support for OpenAPI 2.0, 3.0, 3.1 and 3.2, as well as Postman Collections. It accepts JSON, YAML and YML specifications.</p>
<p>The documented workflow supports two import methods: file upload and URL import. The Document360 CLI can automate either of them in a CI/CD pipeline, so the reference updates whenever the specification changes. The platform generates endpoint articles from the specification and provides a way to review import warnings and errors before publishing the API reference to a developer-facing site.</p>
<p>Each API workspace can contain a maximum of three API references. <mark>That limit is worth checking early for teams that publish several APIs,</mark> such as a public API and a partner API, from the same portal.</p>
<p>Document360 also has a <strong>Try It console</strong> with support for Basic authentication, bearer tokens, API keys, OAuth 2.0 and OpenID Connect.</p>
<p>One detail worth noting is how Document360 handles custom content. The custom content added to generated endpoint articles is retained when the API reference is regenerated or synchronized. This can help <strong>teams add explanations around generated contract</strong> details without losing those additions on the next import.</p>
<h3>Where Document360 may fit</h3>
<p>Document360 is worth evaluating when an organization wants its API reference to live inside a wider documentation portal. The dedicated workspace, publishing controls, reader access settings and CLI workflow may be relevant to teams managing internal, partner-facing or public API references in the same environment.</p>
<h3>What to consider</h3>
<p>The main limitation of this comparison is that Document360 could not be tested hands-on. Document360 does not let you run its CLI for free. You need an account first, and getting one starts with a scheduled call. After the call you sign up, and only then can you use the CLI. Mintlify and Velu need only a CLI install and a local preview, so Document360’s path is <strong><mark>longer and less convenient.</mark></strong> Document360 and GitBook also have CLIs, but those publish a specification to the platform. Unlike the Mintlify and Velu CLIs, they do not start a local preview.</p>
<p>Document360 also does not publish fixed prices. Its pricing information describes custom quotes based on an organization’s requirements. API documentation is available on paid plans only, and each paid plan includes one API workspace. Additional workspaces can be purchased separately.</p>
<p>That makes the cost hard to estimate before you talk to sales. A small team can’t compare it with Mintlify or GitBook until it has a quote.</p>
<blockquote>
<p>Document360 is a candidate when your API reference needs to sit inside a wider portal with controlled publishing and access. Its value is <strong>hard to judge without a quote and a hands-on trial.</strong></p>
</blockquote>
<h2>What the comparison tells us</h2>
<p>The four platforms can all generate API reference content from a machine-readable contract. The more useful differences <strong>are in the workflow around that contract:</strong> how it enters the product, how changes are published and how much of the result could be verified directly as a new user.</p>
<table>
<thead>
<tr>
<th>Capability</th>
<th>Mintlify</th>
<th>GitBook</th>
<th>Velu Docs</th>
<th>Document360</th>
</tr>
</thead>
<tbody><tr>
<td>OpenAPI input</td>
<td>JSON and YAML in the project repository</td>
<td>YAML and JSON through upload, URL or CLI</td>
<td>OpenAPI file referenced in <code>velu.json</code>; the test used JSON</td>
<td>OpenAPI 2.0 to 3.2 and Postman Collection</td>
</tr>
<tr>
<td>Generated endpoint pages</td>
<td>Tested</td>
<td>Tested</td>
<td>Tested</td>
<td>Described in vendor documentation</td>
</tr>
<tr>
<td>Authentication rendering</td>
<td>Verified in generated page</td>
<td>Verified in generated page</td>
<td>Verified in generated page</td>
<td>Supported in documented API workflow</td>
</tr>
<tr>
<td>Parameters and schemas</td>
<td>Verified in generated page</td>
<td>Verified, including Models</td>
<td>Verified, including Models</td>
<td>Generated from imported specification</td>
</tr>
<tr>
<td>Request and response examples</td>
<td>cURL and JSON examples in the test</td>
<td>HTTP examples and response content in the test</td>
<td>Playground-oriented workflow</td>
<td>Generated reference; depends on the specification</td>
</tr>
<tr>
<td>Interactive testing</td>
<td>Yes</td>
<td>Yes</td>
<td>Yes</td>
<td>Try It console</td>
</tr>
<tr>
<td>Shared models</td>
<td>Rendered from OpenAPI structure</td>
<td>Explicit Models section in the test</td>
<td>Rendered from OpenAPI structure</td>
<td>Generated API articles</td>
</tr>
<tr>
<td>Source specification access</td>
<td>File remains in Git</td>
<td>Download option in reference sidebar</td>
<td>File remains in project</td>
<td>Managed through import and resync workflow</td>
</tr>
<tr>
<td>Git or CI automation</td>
<td>Git-based project workflow; web editor commits to the repository</td>
<td>Git Sync, URL and CLI options; upload and editor in the app</td>
<td>Git-based project workflow</td>
<td>URL import and <code>d360</code> CLI</td>
</tr>
<tr>
<td>AI tool access</td>
<td>Hosted documentation MCP server; supports Cursor and Claude Code</td>
<td>MCP server for AI tools including Cursor and Claude Code</td>
<td>MCP and machine-readable documentation outputs described in Velu's documentation</td>
<td>MCP connector for compatible assistants, including Cursor; Claude uses its connector flow</td>
</tr>
<tr>
<td>Hands-on evidence in this comparison</td>
<td>Strong</td>
<td>Strong</td>
<td>Strong</td>
<td>Not completed</td>
</tr>
</tbody></table>
<img src="https://cdn.hashnode.com/uploads/covers/6aa3a41bb290e89589f06fcf/7ddeacb0-fd6b-4184-b3db-b1c7970f0f65.png" alt="" style="display:block;margin:0 auto" />

<p>A few things are worth keeping in mind when reading the table.</p>
<ul>
<li>First, support for an interactive playground does not mean an API is automatically ready to test. The specification needs a valid server URL and the correct security configuration. The target API environment also needs to be reachable. A playground gives developers a way to send requests; it does not replace a working staging environment.</li>
<li>Second, accepting an OpenAPI file is not the same as having an automated publishing process. A manual upload may be fine for an API that rarely changes. If the specification changes with every release, the team needs a repeatable way to validate and publish those changes.</li>
<li>Third, AI access deserves a separate evaluation. Mintlify, GitBook and Document360 document MCP connections for compatible AI assistants. Velu describes MCP and machine-readable outputs. These connections can help Cursor or Claude Code search and retrieve documentation during a coding task.</li>
<li>A documentation MCP server of this kind searches and reads the docs, though. Mintlify's included server, for example, does not call the API itself. An MCP connection also does not guarantee that an assistant will choose the right page, understand an incomplete specification or generate correct code. Test retrieval with real developer questions before making MCP support a deciding factor.</li>
</ul>
<h2>Pricing: What does API documentation actually cost?</h2>
<p>Pricing can change the comparison considerably here and just comparing the entry price of each product can be misleading. A plan may include AI assistants, analytics, access controls or collaboration features that a team does not need just to publish an API reference.</p>
<p>The prices below are the public prices listed on the vendors' websites on <strong>November 19, 2026</strong>. They are in US dollars. Check the pricing pages before purchasing because prices and plan limits can change.</p>
<table>
<thead>
<tr>
<th>Platform</th>
<th align="right">Public entry price</th>
<th>What to know about API documentation</th>
</tr>
</thead>
<tbody><tr>
<td>Mintlify</td>
<td align="right">Free: $0/month</td>
<td>The Free plan includes Git sync, custom domain, authentication, MCP server and API playground for up to five editors. Pro is $450/month with annual billing or $540/month with monthly billing.</td>
</tr>
<tr>
<td>GitBook</td>
<td align="right">Free: $0/site/month</td>
<td>Free includes interactive API playgrounds. Essential starts at $65/site/month plus $12/user/month. Ultimate starts at $249/site/month plus $12/user/month. Paid prices are based on annual billing.</td>
</tr>
<tr>
<td>Velu</td>
<td align="right">Forever free: $0/month</td>
<td>The free plan includes API reference from OpenAPI, the playground, CLI, MCP and Git sync. Begin is $9/month ($90/year) and Value is $49/month ($490/year).</td>
</tr>
<tr>
<td>Document360</td>
<td align="right">Custom quote</td>
<td>API documentation is available on paid plans. One API workspace is included; additional workspaces cost extra.</td>
</tr>
</tbody></table>
<p><strong>Mintlify: The API playground doesn’t need Pro</strong></p>
<p>The Free plan covers up to five editors and includes the API playground, Git sync, a custom domain, authentication and an MCP server.</p>
<p>Pro <strong>costs $450 per month</strong> with annual billing, or $540 with monthly billing. It adds unlimited editors, an assistant, a writing agent, Autopilot and preview deployments. None of these are required to generate an API reference from OpenAPI.</p>
<p>For API documentation alone, start with the Free plan. Upgrade when a specific Pro feature solves a real requirement.</p>
<h4>GitBook: Free to start, then per site and per user</h4>
<p>The Free plan includes interactive API playgrounds and GitHub or GitLab sync.</p>
<p>Paid plans charge for each site and for each user, with annual billing. Essential, which GitBook previously called Premium, costs $65 per site per month plus $12 per user. Ultimate costs $249 per site per month plus the same $12 per user.</p>
<p>With five paid users, one site costs $125 per month on Essential and $309 on Ultimate. The upgrade is mainly about branding, publishing and collaboration, not the API reference itself.</p>
<h4>Velu Docs: Low cost and high value</h4>
<p>Velu lists three plans: Forever free at $0, Begin at $9 per month ($90 per year) and Value at $49 per month ($490 per year). The free plan already includes API reference documentation generated from your OpenAPI file, the playground, the CLI, MCP and Git sync, so the full API workflow costs nothing to start. The paid plans add features such as a custom domain, reader-facing AI answers and automated documentation updates.</p>
<h4>Document360: ask for a quote</h4>
<p>Document360 prices are quote-based. API documentation requires a paid plan, and each paid plan includes one API workspace. Additional workspaces cost extra.</p>
<h2>Which platform should you choose?</h2>
<p>The comparison does not point to one winner for every API team. It points to different strengths, depending on how the team works.</p>
<h3>Choose GitBook for the quickest start in the browser UI</h3>
<p>GitBook was the easiest platform to integrate in this test. Uploading the YAML file and generating the OpenAPI Reference section produced the expected endpoint and model pages without setting up a separate project first.</p>
<p>That makes it a good option for teams that want to get an API reference online quickly. The free plan also includes an API playground and Git Sync, so a team can evaluate the core experience before paying for a branded team site.</p>
<h3>Choose Mintlify when the repository is the starting point</h3>
<p>Mintlify is a natural fit when the API contract already lives in Git and the team wants documentation updates to follow the same process. A repository-first workflow is not exclusive to Mintlify, since GitBook and Velu offers Git Sync too, but it was the more natural starting point in this test.</p>
<p>The OpenAPI file stays in the repository, the site configuration points to it and the documentation build generates the reference. That makes it easier to connect updates to a release workflow, watcher or automation process. Contributors who prefer a browser can use Mintlify's web editor, which commits back to the same repository.</p>
<h3>Evaluate Velu as another configuration-led option</h3>
<p>Velu is worth considering when the team wants a workflow similar to Mintlify's and wants to compare the generated pages, AI outputs and plan costs before deciding.</p>
<p>Its OpenAPI configuration supports a Git-oriented workflow. Its MCP and machine-readable outputs are comparable in kind to what Mintlify and GitBook offer at a very low cost.</p>
<h3>Evaluate Document360 when API reference is part of a governed portal</h3>
<p>Document360 has a dedicated API workspace and documented support for OpenAPI and Postman imports, URL synchronization, CLI-based CI/CD and an interactive Try It console.</p>
<p>That makes it relevant to organizations that need API reference content within a larger portal with controlled reader access and publishing.</p>
<h2>What an API documentation platform cannot do for you</h2>
<p>Generating endpoint pages is <strong>only one part of API documentation.</strong> An OpenAPI specification can describe paths, methods, parameters, request bodies, responses, schemas and security schemes. It does not automatically explain why an endpoint exists, how an integration should be designed or which sequence of calls a developer should make to complete a task.</p>
<p>Take the Notes API used in this comparison. A developer may need to obtain a token, create a session, end that session and retrieve the resulting note. The endpoint pages describe those individual operations. A guide needs to explain the workflow as a whole and the decisions the developer needs to make along the way.</p>
<p>That distinction matters even when a platform generates an excellent API reference. The generated pages are the reference layer and they do not replace conceptual guides, tutorials or task-based examples.</p>
<p>There are a few other limits to keep in mind:</p>
<ul>
<li><strong>The specification still needs to be correct.</strong> If the OpenAPI file has the wrong required fields, response codes or authentication scheme, the generator can reproduce those mistakes accurately.</li>
<li><strong>Examples need to reflect real API behavior.</strong> Generated examples are only as useful as the examples and schemas in the source contract. Review them against actual API responses.</li>
<li><strong>A playground needs a working environment.</strong> A Try It button will not fix a placeholder server URL or an unavailable staging API.</li>
<li><strong>Import support is only the first step.</strong> Teams still need to decide when the specification is published, how changes are validated and what happens when an import fails.</li>
<li><strong>Custom explanations need a maintenance plan.</strong> If writers add content around generated operations, they need to know whether that content survives regeneration and how conflicts are handled.</li>
</ul>
<blockquote>
<p>A documentation platform can make an API reference easier to generate, publish and maintain. It cannot replace a reliable API contract or thoughtful developer guides.</p>
</blockquote>
<h2>The verdict</h2>
<p>After using the same Notes API contract across these four platforms, the choice comes down to the team's workflow rather than a universal winner. GitBook was the quickest way to go from a file to a published reference in the browser, and Mintlify was the most natural fit when the repository is the starting point. Both also support the other route, through Git Sync in GitBook and a web editor in Mintlify.<br /><br />Velu is worth a trial because its workflow is close to Mintlify's and its paid plans start at $9 and $49 per month, and Document360 when a governed portal is a real requirement. <mark>For a small API team, I would start with</mark> <strong><mark>Velu</mark></strong> <mark>or</mark> <strong><mark>GitBook</mark></strong> <mark>as they are easy, free and low price.</mark></p>
<p>In the end, the decision comes down to three things: <strong><mark>the quality of the generated reference, the effort required to keep it in sync with the API and the cost of the plan the team actually needs.</mark></strong></p>
]]></content:encoded></item><item><title><![CDATA[Technical Writers Should Be the Ones Writing AI Skill Files]]></title><description><![CDATA[Learn what an AI skill file (SKILL.md) is, why technical writers are best at writing them and how one turns a PRD into consistent docs drafts.]]></description><link>https://tech-writing.hashnode.dev/technical-writers-should-be-the-ones-writing-ai-skill-files</link><guid isPermaLink="true">https://tech-writing.hashnode.dev/technical-writers-should-be-the-ones-writing-ai-skill-files</guid><category><![CDATA[technical writing]]></category><category><![CDATA[AI]]></category><category><![CDATA[documentation]]></category><category><![CDATA[claude]]></category><category><![CDATA[agents]]></category><category><![CDATA[ai agents]]></category><category><![CDATA[skills]]></category><dc:creator><![CDATA[Harshit Satyaseel]]></dc:creator><pubDate>Tue, 17 Nov 2026 08:10:23 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/covers/6aa3a41bb290e89589f06fcf/6b5748b6-03ab-4435-96f4-db4e7ca714e4.png" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p>If you use AI to write documentation, you’ve probably seen this happen more than once. One prompt gives you a page that follows your style guide perfectly. The next prompt forgets your heading style, renames your product, and writes the release notes in a format your team stopped using a year ago, so you end up pasting the same instructions into every conversation and fixing the same mistakes in every draft. For a while I thought this was just the price of working with AI. Then I started writing skill files, and I realised that the fix for this problem looks a lot like the work technical writers already do every day.</p>
<h3>What a skill file actually is</h3>
<blockquote>
<p>A skill file is a set of instructions that teaches an AI tool how to do one specific task the way you want it done. In practice, a skill is a folder containing a <a href="http://SKILL.md"><strong>SKILL.md</strong></a> file.</p>
</blockquote>
<p>It includes a name and a description at minimum, along with instructions that tell the agent how to perform the task. It can also bundle scripts, reference materials and templates. The name and description sit at the top of the file and tell the AI when the skill is useful, while the rest of the file is plain Markdown that explains how to do the work.</p>
<blockquote>
<p><br /><mark>Looking for a SKILL file sample that turns your PRD into an actionable, ready-to-review draft? Check out -</mark> <a href="https://satyaseel.gumroad.com/l/vyjyip"><mark>PRD TO DOCS AI SKILL</mark></a></p>
</blockquote>
<p><a class="embed-card" href="https://satyaseel.gumroad.com/l/vyjyip">https://satyaseel.gumroad.com/l/vyjyip</a></p>

<p>The clever part is how the AI reads it. The agent scans the descriptions, and when one matches the current task, the whole skill, including its instructions and supporting files, enters the agent’s context. That means you can keep many skills ready without filling every conversation with instructions the AI doesn’t need yet, and the right one loads only when you ask for that kind of work.</p>
<p>Skill files also aren’t tied to one tool anymore. Anthropic shipped skills in October 2025 and published the format as an open standard on December 18, 2025, and the official showcase now lists more than 40 tools that support it, including GitHub Copilot, VS Code, Cursor, Gemini CLI and OpenAI’s Codex. So a skill you write once can work in whichever AI tool your team happens to use.</p>
<blockquote>
<p>The easiest way I’ve found to explain the difference between a prompt and a skill file is to think about onboarding.</p>
<ul>
<li>A <strong>prompt</strong> is like explaining a task to a new teammate in a quick chat, which works once but is gone the next day.</li>
<li>A skill file is the onboarding document you hand them on day one, with your style rules, your templates and a checklist for what good work looks like, so every task they do after that starts from the same place.</li>
</ul>
</blockquote>
<h3>Why technical writers are the right people to write them</h3>
<p>When you look closely at a skill file, it’s really documentation, except the reader is an AI that follows every word it has.</p>
<p>Most of the skills of a good skill file are skills we already use at work:</p>
<ul>
<li><strong>Structure:</strong> We know how to turn messy information into a clear structure, which is exactly what a skill needs. Style guides, templates and information architecture are part of our daily work, and frameworks like Diátaxis already teach us that a how-to guide and a feature overview need different structures.</li>
<li><strong>Clear language:</strong> We’re trained to remove ambiguity, because ambiguous instructions confuse AI in the same way they confuse users. A rule like “keep it consistent” means nothing to an AI. A rule like “use sentence case for headings and bold only UI labels” produces the same result every time.</li>
<li><strong>Defined terms:</strong> We define terms before we use them, which stops the AI from inventing its own names for your features.</li>
<li><strong>Knowing what good output looks like:</strong> We already review docs every day, so we know how to tell when a draft is right. A skill without a final checklist will happily produce confident drafts that are wrong, and writing that checklist comes naturally to someone who reviews documentation for a living.</li>
<li><strong>Knowing the workflow:</strong> We sit between product, engineering and support, so we know the full path a feature takes from a PRD to release notes. Engineers are writing excellent skills for coding tasks, but a skill for documentation needs someone who understands what users need from the docs and where they usually get stuck.</li>
</ul>
<h3>What a good skill file changes in your day</h3>
<p>The biggest change for me was how much <strong>repeated manual work disappeared.</strong> Before I used skills, a lot of my time went into pasting the same style rules, correcting product names, rebuilding page structures and reformatting release notes into our five standard sections. Once those rules lived in one skill file, I stopped fixing them by hand, because every draft started from the same instructions.</p>
<p>The second change was <strong>consistency across the team</strong>. When every writer uses the same skill, drafts from different people come back with the same structure, the same terms and the same tone. Reviews get faster as a result, because the reviewer is checking facts instead of formatting.</p>
<p><mark>I want to be honest about what a skill file doesn’t change, though.</mark> The AI still writes the first draft, and you still have to check every field, every default and every step against the real product before anything ships. A good skill makes that checking easier, because the drafts are predictable and the open questions are listed up front, but it doesn’t remove the need for a writer who knows the product.</p>
<h3>From one PRD to five consistent drafts</h3>
<p>The task where a skill file has saved me the most time is turning a product requirements document into docs. When a PRD lands, the usual routine is to r<strong>ead it a few times,</strong> list the questions for the product manager, wait for answers, and then write the feature overview, the how-to guide and the release notes one by one. Each of those pages follows rules your team has agreed on, and every one of those rules is something the AI has to be told.</p>
<p>So I packaged the skill I use for this into a product called the <a href="https://satyaseel.gumroad.com/l/vyjyip"><strong>PRD to Docs AI Skill</strong>.</a> You give the AI a PRD, and the skill produces five drafts that follow the same structure every time:</p>
<ol>
<li><strong>A questions log:</strong> This lists the few questions that decide whether the docs are correct, with the assumption taken for each one, so you can start writing before the PM replies.</li>
<li><strong>A glossary:</strong> It gives one plain definition for every new term.</li>
<li><strong>A feature overview:</strong> It explains what the feature does and who can use it.</li>
<li><strong>A how-to guide:</strong> It covers the main task from start to finish.</li>
<li><strong>Release notes:</strong> These are split into What’s new, What’s enhanced, What’s changed, Deprecated and Removed.</li>
</ol>
<p>The questions log is my favourite part. In my experience, a wrong assumption costs more time than a slow draft, and seeing the risky assumptions listed before any writing starts changes how the whole review goes.</p>
<p>To make the skill yours, you fill in a few settings and a short profile of your company, such as your product names and your voice. From then on, every draft reads like your docs instead of generic AI output. The package includes the full <a href="http://SKILL.md">SKILL.md</a> file, a finished example company profile, a ZIP ready to upload to Claude and a 24-page setup guide. It works best in Claude and Claude Code, and you can paste the same instructions into other AI tools too.</p>
<h3>How to start writing your own skill file</h3>
<p>You don’t need my skill to get started, and I’d encourage every technical writer to try writing one, because it’s quickly becoming part of the job. These steps are a good place to begin:</p>
<ol>
<li><strong>Pick one recurring task:</strong> Release notes work well, because they follow the same format every time and take more time than they should.</li>
<li><strong>Write down what good looks like:</strong> Add one real example your team approved, so the AI has a model to match instead of guessing.</li>
<li><strong>Turn every preference into a specific rule:</strong> Replace adjectives like “clear” or “consistent” with instructions the AI can follow exactly.</li>
<li><strong>Add a final checklist:</strong> List what the AI must confirm before it hands you the draft, such as product names, headings and section order.</li>
<li><strong>Test it on two or three real inputs:</strong> When a draft comes back wrong, fix the skill instead of the draft, so the same mistake doesn’t come back next time.</li>
</ol>
<h3>Conclusion</h3>
<p>AI can write first drafts faster than any of us, but it still needs someone to tell it what good documentation looks like. That person should be the technical writer. We already know the structure, the rules, the terms and the checks, and a skill file is just the place where all of that finally gets written down for a new kind of reader.</p>
<p>If you’d like a working example to learn from or build on, the PRD to Docs AI Skill is a good starting point. Either way, I’d love to know whether you’ve written a skill file for your docs work yet, and which task you would automate first. Tell me in the comments.</p>
]]></content:encoded></item><item><title><![CDATA[How To Set Up Vale To Enforce Your Docs Style Guide Automatically]]></title><description><![CDATA[Learn how to set up Vale to automate your docs style guide. Write custom rules, CI integration, setup, vocabulary files, and real production examples.]]></description><link>https://tech-writing.hashnode.dev/how-to-set-up-vale-to-enforce-your-docs-style-guide-automatically</link><guid isPermaLink="true">https://tech-writing.hashnode.dev/how-to-set-up-vale-to-enforce-your-docs-style-guide-automatically</guid><category><![CDATA[AI]]></category><category><![CDATA[documentation]]></category><category><![CDATA[Technical writing ]]></category><category><![CDATA[vale]]></category><category><![CDATA[DocumentationBestPractices]]></category><category><![CDATA[technical writing]]></category><category><![CDATA[automation]]></category><category><![CDATA[mintlify]]></category><dc:creator><![CDATA[Harshit Satyaseel]]></dc:creator><pubDate>Wed, 23 Sep 2026 17:01:13 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/covers/6aa3a41bb290e89589f06fcf/56a6914d-2065-4685-b287-6412bbd76a6d.png" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p>In technical writing, most of us follow a style guide. But what is a style guide? In simple terms, a style guide is a set of rules your docs team follows to write consistently, so your docs feel the same no matter how many writers write them.</p>
<p>The style guide defines the rules and the ways of doing things like how to capitalise product names, which terms to use and which to avoid, whether headings should be sentence case or title case, things like whether you write "e.g." or "for example," how you format code references, and dozens of other small rules.</p>
<p>These rules make sure that your docs feel consistent and polished. If someone read them, it must feel like five different people wrote them without talking to each other.</p>
<p>At the place I work, I own the style guide formatting and rules. In this blog, I will explain how to automate your style guide rules as your product docs scale using Vale.</p>
<div data-node-type="callout">
<div data-node-type="callout-emoji">💡</div>
<div data-node-type="callout-text"><p>Looking for an end-to-end Technical Writer Career Kit? Check this out?</p></div>
</div>
<p><a class="embed-card" href="https://satyaseel.gumroad.com/l/lugozs">https://satyaseel.gumroad.com/l/lugozs</a></p>

<h2>Why style guides as documents don't work well</h2>
<p>Style guides as a document don't work well, and it is easy to ignore them as you add more product docs. When your team scales or when engineers start contributing docs alongside the writing team, they are not even aware that you write things in a certain way. This is where things start falling apart, consistency takes a hit, and it's hard to fix. So the style guide exists to keep everyone aligned, but the problem is in how it gets delivered and shared well.</p>
<p>It is a general practice that most style guides live as a Confluence page, a Google Doc, or as a PDF in SharePoint. Somebody wrote it, pinned it in Slack once, and assumed people would read it before every writing, but this never happens. Also, you can't chase people all the time to read a big style guide and understand how to write as per the rules.</p>
<p>That's where Vale comes in. Once you wire it into your docs repo the right way, those inconsistencies mostly disappear, not because people memorised the guide, but because the guide started running itself at commit and on every PR.</p>
<p>I will show you how I set that up so you can understand how you can do the same.</p>
<h2>What is Vale and how is it different from Grammarly</h2>
<p>Vale is an open-source command-line tool that checks your writing against rules you define. It is a single Go binary, so you download it, and it works, and there is no more dependency needed.</p>
<p>Now, people confuse Vale with Grammarly a lot, so let me be clear about the difference. Grammarly checks your grammar and suggests rewrites. Vale does not do any of that. It only checks rules you define, and if you don't give it any rules, it does nothing.</p>
<p>Grammarly is fine if your team won't touch a terminal and you need a quick starting point, but if you already treat docs like code, with Git, pull requests, and CI, then Vale is the tool that fits into that workflow.</p>
<h2>How Vale works: Rules, Styles, and Config</h2>
<p>Vale works on three concepts, and once you understand them, you understand the whole process of how to write rules that work well and follow your style guides.</p>
<ul>
<li><strong>Rule:</strong> A rule in Vale is a single YAML file you define to check one single thing. For example, one rule to ban the word "simply," another rule to replace "e.g." with "for example."</li>
<li><strong>Style:</strong> A style is just a folder that holds a bunch of rules you defined. The folder's name becomes the style name. Suppose your folder is named <code>Docs</code> and your rule file name is <code>NoFiller.yml</code>, Vale calls it <code>Docs.NoFiller</code> in its output.</li>
<li><strong>Config:</strong> A config is a single file called <code>.vale.ini</code> that sits at the root of your repo. It tells Vale which styles to run, on which files, and what to skip.</li>
</ul>
<p>But here is the most important part that most Vale tutorials skip. Many modern docs sites are not just text. They have YAML frontmatter, JSX component titles, fenced code blocks, inline code references, and navigation JSON. If you point Vale at all of this without telling it what to skip, you get hundreds of false positives, which is something hard to fix later. So to avoid this, treat Vale as a body-prose linter, not a whole-repo text checker.</p>
<h2>What to do before writing any Vale rules</h2>
<p>Explore and find the issue you have. When I was trying to use Vale, I went through my existing docs and pulled out every inconsistency I could find, like product names spelt wrong, terms used differently across pages, filler words that kept showing up, etc. Then I sorted those findings into three tiers:</p>
<img src="https://cdn.hashnode.com/uploads/covers/6aa3a41bb290e89589f06fcf/e45c9b1b-47f2-4ba5-89fe-373f9859a69a.png" alt="" style="display:block;margin:0 auto" />

<ol>
<li><strong>Tier 1</strong>: It is the stuff that is safe to auto-fix everywhere; for example, product name casing, banned synonyms, filler words. These become Vale substitution and existence rules.</li>
<li><strong>Tier 2:</strong> It is the stuff that depends on context. Say the same concept might appear as "Access Token" in a conceptual guide, <code>accessToken</code> in SDK docs, and <code>access_token</code> in REST API docs. All three are correct, just in different places. Vale can detect the finding, but you need a wrapper script to suggest the right form based on which folder the file is in.</li>
<li><strong>Tier 3:</strong> It is code identifiers that must stay exactly as they are. For example: <code>accessToken</code>, <code>access_token</code>, camelCase SDK properties. Vale must know it needs to skip these, not try to fix them.</li>
</ol>
<p>I got the team to review and approve the preferred terms before writing any rules with the engineering team. That review document became the source of truth that I used to define the Vale rules. If you skip these steps and go straight to writing rules, you will end up with the wrong fixes and spend months fighting your own CI checks.</p>
<h2>How to install Vale and set up your first config</h2>
<p>Install Vale by running the following as per your system and OS.</p>
<pre><code class="language-bash"># macOS
brew install vale

# Windows
choco install vale
# or: winget install vale

# Linux
snap install vale
# or download the binary from https://github.com/errata-ai/vale/releases
</code></pre>
<p>Now create a <code>.vale.ini</code> file at the <strong>root</strong> of your repo. Here is what my looks like for a docs repo that has MDX files.</p>
<pre><code class="language-ini">StylesPath = .vale/styles
MinAlertLevel = suggestion
Vocab = Product

# Treat MDX files as Markdown
[formats]
mdx = md

# Published docs — Vale checks these
[*.mdx]
BasedOnStyles = Docs

# Maintainer Markdown — Vale stays out
[*.md]
BasedOnStyles =

# Generated pages — Vale stays out
[updates/newsletter-source.mdx]
BasedOnStyles =
</code></pre>
<p>Then run:</p>
<pre><code class="language-bash">vale sync
vale path/to/one-page.mdx
</code></pre>
<p>Notice that I did not tell Vale to lint every Markdown file instead only check the published MDX pages. I had many internal docs like STYLE_GUIDE.md which is excluded.</p>
<p>I also wrapped the CLI in npm scripts so nobody has to remember flags:</p>
<pre><code class="language-bash">npm run check:vale          # staged *.mdx files (pre-commit)
npm run check:vale:changed  # changed files vs origin/main (PR and CI)
npm run check:vale:all      # full audit of all tracked MDX
</code></pre>
<p>And then I added an escape hatch for when someone intentionally wants to skip the check:</p>
<pre><code class="language-bash">VALE_SKIP=1 git commit ...
</code></pre>
<p>An escape hatch that requires intent is fine because if some one just skips them that is how style rules slowly drift.</p>
<h2>How to handle two casing systems in one file</h2>
<p>This is the part that gave me the most trouble, and I have not seen it covered well anywhere.</p>
<p>My style guide has different casing rules for different parts of the page. Body paragraphs use sentence case for product names. UI chrome like Card titles, Tab labels, and hub pills use Title Case. API docs keep REST fields as <code>snake_case</code>. SDK docs keep properties as <code>camelCase</code>.</p>
<p>If Vale enforced body rules on Card titles, every hub page would fail. or if I banned Title Case everywhere, the design system would break. The solution was simple once I figured it out: Vale owns body prose, and the style guide owns chrome. So do not make one tool try to enforce both.</p>
<img src="https://cdn.hashnode.com/uploads/covers/6aa3a41bb290e89589f06fcf/2a131b12-9ec9-481e-be53-33c8791ea0cf.png" alt="" style="display:block;margin:0 auto" />

<p>In <code>.vale.ini</code>, this meant adding <code>TokenIgnores</code> and <code>BlockIgnores</code> to skip inline code, JSX attributes, frontmatter, and fenced code blocks:</p>
<pre><code class="language-ini">[*.mdx]
BasedOnStyles = Docs
TokenIgnores = (\x60[^\n\x60]+\x60), (\b[A-Za-z][\w-]*\s*=\s*"[^"]*")
BlockIgnores = (?s)\A---\n.*?\n---\n, (?s)\n[ \t]*```[^\n]*\n.*?\n[ \t]*```
</code></pre>
<div data-node-type="callout">
<div data-node-type="callout-emoji">💡</div>
<div data-node-type="callout-text"><p><strong>One key point - </strong>Use comma-separated regexes in <code>.vale.ini</code>. Pipe alternation like <code>(a|b)</code> can break the INI parser. We found that out the hard way.</p></div>
</div>

<h2>How to write custom Vale rules with real examples</h2>
<p>Follow these rule to define some custom rules.</p>
<h3>Substitution rules: replace the wrong term with the right one</h3>
<p>This is the rule type I use most. It handles Tier 1 findings, the things that is safe to auto-fix everywhere.</p>
<pre><code class="language-yaml"># .vale/styles/Docs/Terms.yml
extends: substitution
message: "Use '%s' instead of '%s'."
link: https://example.com/STYLE_GUIDE.md#terminology
level: warning
ignorecase: false
scope:
  - text
swap:
  web SDK: Web SDK
  Web sdk: Web SDK
  "Form Builder": Form builder
  websocket: WebSocket
  realtime: real-time
  doctor user: clinician
</code></pre>
<p>Start with the variants your docs scan actually found and don't sit down and imagine every possible mistake as it is easy to over-engineer it.</p>
<h3>Existence rules: ban words that should not be there</h3>
<p>This is for filler words and other things you don't want at all.</p>
<pre><code class="language-yaml"># .vale/styles/Docs/NoFiller.yml
extends: existence
message: "Avoid filler words like '%s' in docs."
level: warning
ignorecase: true
tokens:
  - simply
  - just
  - obviously
  - easily
  - basically
</code></pre>
<p>I also used existence rules with regex for trickier cases, like capitalising a product noun only at the start of a sentence:</p>
<pre><code class="language-yaml"># .vale/styles/Docs/SentenceProductNoun.yml
extends: existence
message: "Capitalize Sync at sentence start or in a product list."
level: warning
scope: raw
nonword: true
tokens:
  - '(?&lt;=[.!?]\s)sync '
  - '(?&lt;![`A-Za-z])sync APIs?\b'
  - '\x5bsync '
</code></pre>
<p>Honestly, these took a few rounds to get right but when these rules flagged perfectly valid sentences, I kept narrowing the tokens until false positives stopped.</p>
<h3>Handling credentials that have three correct forms</h3>
<p>This was Tier 2, and honestly the biggest win after product casing. The same credential appears differently depending on context:</p>
<table>
<thead>
<tr>
<th>Context</th>
<th>Correct form</th>
</tr>
</thead>
<tbody><tr>
<td>Narrative prose</td>
<td>Access Token</td>
</tr>
<tr>
<td>SDK docs</td>
<td><code>accessToken</code></td>
</tr>
<tr>
<td>REST API docs</td>
<td><code>access_token</code></td>
</tr>
</tbody></table>
<p>A substitution rule that always forces "Access Token" would break every API reference page. So I split it: Vale flags the miscased form using an existence rule, and a small Node wrapper script reads the finding, checks which folder the file is in, and prints the right suggestion:</p>
<pre><code class="language-plaintext">Found:       access token
Use instead: `access_token`
Note:        API docs — use snake_case field name in backticks.
</code></pre>
<p>Same finding in an SDK guide suggests <code>accessToken</code> instead. Vale handles detection. The wrapper handles context. That script lives at <code>scripts/check/check-vale.mjs</code> and is what npm and CI actually call.</p>
<h3>Vocabulary files: your product's accept and reject list</h3>
<p>Instead of writing a substitution rule for every single product name, I use Vale's vocabulary feature. It is just two text files:</p>
<ul>
<li><code>accept.txt</code> has your approved terms with exact casing: JavaScript, TypeScript, PostgreSQL, and also SDK property names like <code>accessToken</code> so Vale doesn't flag them as misspelled.</li>
<li><code>reject.txt</code> has terms you never want in body prose: k8s, JS, Postgres.</li>
</ul>
<p>When a term changes, you update one line in one file. Much easier than maintaining a giant substitution rule.</p>
<h2>How to run Vale in CI on every pull request</h2>
<p>Running Vale locally is useful but the aim is to run it in CI which actually changes how you work in a team as now a style violation blocks the PR.</p>
<img src="https://cdn.hashnode.com/uploads/covers/6aa3a41bb290e89589f06fcf/9c813cae-e230-4829-8990-a86ecb777d50.png" alt="" style="display:block;margin:0 auto" />

<pre><code class="language-yaml"># .github/workflows/vale-prose.yml
name: Vale prose check
on:
  pull_request:
    paths:
      - '**/*.mdx'
      - '.vale/**'
      - '.vale.ini'
      - 'scripts/check/check-vale.mjs'
jobs:
  vale:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Install Vale
        run: |
          VALE_VERSION=3.14.2
          curl -sfL "https://github.com/errata-ai/vale/releases/download/v${VALE_VERSION}/vale_${VALE_VERSION}_Linux_64-bit.tar.gz" \
            | tar -xz -C /tmp
          sudo mv /tmp/vale /usr/local/bin/vale
      - run: node scripts/check/check-vale.mjs --changed
</code></pre>
<div data-node-type="callout">
<div data-node-type="callout-emoji">💡</div>
<div data-node-type="callout-text"><p>Two things to note: I only lint changed MDX files, not the entire repo and second is that I pin the Vale version so CI and local machines don't drift.</p></div>
</div>

<h2>Best practices for Vale folder structure</h2>
<img src="https://cdn.hashnode.com/uploads/covers/6aa3a41bb290e89589f06fcf/f5969003-e466-48be-8b96-71710f0d97a8.png" alt="" style="display:block;margin:0 auto" />

<p>After a few years of using Vale in production, here is what worked for me that I feel worth writing:</p>
<ul>
<li>Keep <code>.vale.ini</code> at the repo root as Vale walks up the directory tree looking for it. If you add it in a subfolder, you will spend an afternoon debugging why rules aren't running.</li>
<li>Put your custom rules in <code>.vale/styles/Docs/</code> and name each file after what it checks: <code>Terms.yml</code>, <code>NoFiller.yml</code>, <code>SentenceProductNoun.yml</code>. When a check fails in CI, the filename should tell you what went wrong without opening the file.</li>
<li>Synced packages like <code>Microsoft/</code> go in <code>.gitignore</code> because <code>vale sync</code> regenerates them. Your custom rules and vocabulary files are the things that belong in version control.</li>
<li>Keep the wrapper script under <code>scripts/check/</code> so it's easy to find and easy to update.</li>
</ul>
<h2>Mistakes I made and how you can avoid them</h2>
<ul>
<li><strong>I enforced body rules on UI chrome -</strong> Card titles and hub pills use Title Case by design. Vale didn't know that and flagged them every time it ran. I kept fixing the titles to match Vale's suggestion, and then the UI looked broken. To fix this, I skiped all chrome in my config using TokenIgnores and BlockIgnores. Body prose and UI chrome are two different casing systems and I just did not enforce both.</li>
<li><strong>Wrote rules that were too broad for my docs -</strong> One early rule that I defined was that "always lowercase a product noun." It worked fine until the word appeared at the start of a sentence, or in a product list like "Sync, Dictation, and Form builder." Both are valid capitalizations, and Vale flagged them anyway. I scrapped it and wrote a narrower existence rule that only fires in specific positions. So learning here is that always start narrow while defining the Vale rule .</li>
<li><strong>I forgot about indented code fences -</strong> My BlockIgnores regex caught regular triple-backtick blocks but code fences indented inside Step or CodeGroup JSX components? The regex missed those. Vale was flagging variable names inside code examples as terminology mistakes so I had to extend the ignore pattern to handle indented fences too.</li>
<li><strong>Linted files that discuss wrong forms on purpose -</strong> My STYLE_GUIDE.md says things like "don't write 'realtime,' write 'real-time.'" The banned word is right there in the sentence because the sentence is explaining the rule. Vale doesn't understand context as it just sees "realtime" and flags it so I excluded those files entirely.</li>
<li><strong>I assumed writers would understand raw Vale output -</strong> Vale's default output looks like <code>MyTeam.Terms: Use 'Web SDK' instead of 'web SDK'</code> with a file path and line number. Other writers looked at it, got confused, and asked someone on Slack. We built a wrapper that prints: <code>Found: web SDK → Use instead: Web SDK → Line 14: configure the web SDK settings.</code> Much clearer, and people started fixing things on their own.</li>
<li><strong>I let AI assistants fight Vale -</strong> I use AI to help draft MDX pages. The AI didn't know our casing rules, so every AI-generated draft failed Vale on commit. To fix this problem, I copied the same terminology rules into the AI's system instructions. Now the AI writes "Web SDK" and "real-time" from the start, and Vale passes on the first try.</li>
</ul>
<h2>When to use Vale or other alternatives</h2>
<p>This totally depends on what you are trying to accomplish. For example:</p>
<ul>
<li><strong>Grammar checking</strong> is not something Vale does at all. For that, use LanguageTool. You can run both side by side without any overlap.</li>
<li><strong>Inclusive language checks</strong> work well as a Vale package. Add <code>alex</code> inside Vale and it catches terms like "master/slave" and gendered language with more depth than you'd want to build yourself.</li>
<li><strong>Prose quality feedback</strong> like catching clichés and redundant phrases ("ATM machine") is handled by the <code>proselint</code> package. Again, runs inside Vale, no separate tool needed.</li>
<li><strong>Teams that won't touch a terminal</strong> are better off starting with Grammarly. No setup, no config files, just a browser extension. You can't customise it with your own rules and it won't run in CI, but it's a realistic first step. Migrate to Vale when the team adopts docs-as-code.</li>
<li><strong>Node.js-heavy teams</strong> already running ESLint and Prettier might prefer textlint. It's slower and the config is more complex, but its plugin ecosystem is larger and it fits naturally into an existing Node toolchain.</li>
</ul>
<h2>Conclusion</h2>
<p>Vale can feel like a lot when you start but you don't need to set up everything all at once. Start small and learn how to use it. Go through your existing docs and note the inconsistencies that keep showing up. Sort them into tiers like I described above and write one substitution rule for your most common product casing mistakes.</p>
<p>Create one accept/reject vocabulary file for your product names and set up ignores so your code blocks and UI chrome don't flood you with warnings. This way, you don't need to share the style guide with anyone or remind them to read it as the checks run automatically every time someone commits and pushes new changes.</p>
]]></content:encoded></item><item><title><![CDATA[I Stopped Sending the Whole Conversation to My RAG System]]></title><description><![CDATA[If you’re building technical docs assistants using RAG pipelines, stop dumping the entire chat transcript into every prompt. If you are currently appending…]]></description><link>https://tech-writing.hashnode.dev/i-stopped-sending-the-whole-conversation-to-my-rag-system</link><guid isPermaLink="true">https://tech-writing.hashnode.dev/i-stopped-sending-the-whole-conversation-to-my-rag-system</guid><dc:creator><![CDATA[Harshit Satyaseel]]></dc:creator><pubDate>Fri, 11 Sep 2026 06:51:24 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/covers/6aa3a41bb290e89589f06fcf/d3dfde70-af99-463c-9af2-a30078d56f4a.png" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p>If you’re building technical docs assistants using RAG pipelines, stop dumping the entire chat transcript into every prompt.</p>
<p><a class="embed-card" href="https://satyaseel.gumroad.com/l/lugozs">https://satyaseel.gumroad.com/l/lugozs</a></p>

<p>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.</p>
<p>Here is what I did to fix this in my RAG pipeline: I built a Scope-Adaptive Context Gate (SADCG).</p>
<img src="https://cdn.hashnode.com/uploads/covers/6aa3a41bb290e89589f06fcf/f1d2fe6a-855d-4153-96b4-1287bb279eff.png" alt="" style="display:block;margin:0 auto" />

<p>Instead of stuffing the prompt, it classifies user intent and filters conversation history by topic scope before RAG retrieval even runs.</p>
<p>What happened after implementing this:<br />• 21% reduction in total per-chat credit cost<br />• Up to 40% lower peak context size<br />• Zero cross-topic hallucination in generated code and API answers</p>
<p>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.</p>
<p>Read the full story on <a href="https://medium.com/@hsatyaseel/i-stopped-sending-the-whole-conversation-to-my-rag-system-785474642d6d">Medium</a></p>
]]></content:encoded></item></channel></rss>