DEV Community: Bipin Rimal

Why Your Fintech API Code Examples Are a Liability

Bipin Rimal — Thu, 12 Mar 2026 14:34:28 +0000

A developer copies a code example from your API docs. Changes the account ID. Updates the amount. Hits send.

The money moves. To the wrong account. Using a deprecated endpoint your docs still show as valid.

In a social media API, a wrong code example posts the wrong image. Embarrassing. In a financial services API, a wrong code example moves money. And Ctrl+Z is not a feature that banking infrastructure supports.

Wrong API examples in fintech aren't documentation bugs. They're operational incidents waiting to happen.

The Numbers

Stat	Source
75% of production APIs have variances from their OpenAPI specs	Nordic APIs / APIContext
70% of devs rate code examples as the #1 most important doc component	SmartBear 2020 State of API
55% of teams struggle with inconsistent/outdated documentation	Postman 2025 State of the API
83% of developers consider doc quality when evaluating an API	Monetizely
71% have chosen one API over another because of better docs	Monetizely

Three-quarters of APIs don't match their own docs. The thing developers trust most is code examples. And doc quality is the deciding factor for most adoption decisions.

3 Ways Code Examples Silently Break

1. The endpoint changes. The example doesn't.

Payments team ships V3 of the transfers endpoint. API reference gets updated. The four code examples in tutorials still point to V2. V2 still works — for now.

# Your docs still show this:
POST /v2/transfers

# Your API is actually on:
POST /v3/transfers

Developer builds an entire integration on a deprecated path.

2. A required field gets added. The example lies.

Compliance mandates a new purpose_code field on international transfers. The API rejects requests without it. But the quickstart guide doesn't include it.

// What your docs show:
{
  "amount": 10000,
  "currency": "USD",
  "destination": "acct_xxx"
}

// What the API actually requires:
{
  "amount": 10000,
  "currency": "USD",
  "destination": "acct_xxx",
  "purpose_code": "P0101"  // 400 error without this
}

3. Default values change. Silently.

Your API defaults settlement_speed from "standard" (T+1) to "instant". The code example doesn't specify the field because "the default is fine."

Every developer copying that example now gets instant settlement — with different fees — and doesn't know it.

This is the one that should terrify you.

The Real-World Cost

This isn't theoretical:

PayPal had endpoints listed in docs that didn't exist, undocumented webhook delays, and session timeouts merchants discovered through trial and error — in production
Healthcare: A deprecated SOAP endpoint remained accessible for 6 months while vulnerabilities were only patched in newer REST services. 450,000 patient records exposed.
Financial services: Average $300,000+ per hour in API-related downtime costs
Failed payments cost the global economy $118.5 billion annually

Write Once, Pray Forever

Here's how fintech API documentation actually works in practice: An engineer writes a feature, someone writes the docs and code examples, and on the day they're written, everything is accurate. Then the feature evolves over 6-12 months. The API reference gets updated — maybe. But the code examples scattered across guides and tutorials? Almost certainly not.

76% of failed API integrations result from inadequate documentation or support.

What Stripe, Twilio, and Plaid Do

Stripe: SDK generation pipeline built on Ruby DSL → OpenAPI specs → auto-generated library code in multiple languages. They also built and open-sourced Markdoc. Interactive examples see 62% higher engagement.

Twilio: Migrated 5,000+ pages with Yoyodyne. Samples update automatically when API or codegen tool changes. Zero manual sync.

Plaid: Discovered developers bypassed navigation for search. Expanded their search index by hundreds of entries. Behavior data drives docs improvement.

Common thread: They treat code examples as testable code, not documentation text.

Your 4-Week Safety Net

Week 1: Audit your quickstart. Fresh environment. Run every example.
Week 2: Fix the broken quickstart examples. Highest traffic first.
Week 3: Add example testing to CI. One file, one test. Fail the build.
Week 4: Expand to top 5 integration guides. Set up freshness tracking.

Tools That Help

Tool	What It Does
Pact	Contract testing — catches breaking API changes before production
Vale	Open source prose linter for style guide enforcement
EkLine	Managed docs automation — style, links, terminology on every PR in CI/CD
Spectral	OpenAPI linting — catches spec drift

The Bottom Line

In most software, documentation that's 95% accurate is fine. In financial services, the 5% that's wrong is where someone loses money.

Outdated docs isn't a typo. It's a bug. In fintech, that bug moves money.

We'll be at Fintech Meetup at the end of March. If any of this resonated, let's connect. ekline.io

Docs-as-Code: The Complete CI/CD Workflow (From Git to Production)

Bipin Rimal — Tue, 03 Mar 2026 18:07:30 +0000

You know what docs-as-code is. I'm not going to explain it for the 900th time. Store docs in Git, write in Markdown, review through PRs, deploy through CI/CD. Got it. Moving on.

What nobody seems to write about is what a working pipeline actually looks like. The real config files, the real tradeoffs, the stuff that took us three iterations to get right. Every "docs-as-code guide" I've read either stops at the philosophy or gives you a toy example that falls apart the moment you have more than five pages.

This is the actual pipeline. Config files you can copy. Decisions explained so you understand why, not just what. Opinions included at no extra charge.

Repository Structure

Start with a layout that scales. Here's what works:

your-product/
├── docs/
│   ├── getting-started/
│   │   ├── quickstart.md
│   │   ├── installation.md
│   │   └── first-project.md
│   ├── guides/
│   │   ├── authentication.md
│   │   ├── configuration.md
│   │   └── deployment.md
│   ├── api-reference/
│   │   ├── endpoints.md
│   │   └── error-codes.md
│   ├── assets/
│   │   └── images/
│   └── index.md
├── .github/
│   └── workflows/
│       └── docs.yml
├── .vale.ini              # Style linting config
├── .lychee.toml           # Link checker config
├── cspell.json            # Spell checker config
└── .ekline/
    └── config.yaml        # EkLine config (if using)

Now, before you blindly copy this, let me explain the decisions, because they matter more than the structure.

Docs live in the same repo as code. Not a separate repo. This is the hill I will die on. When an engineer changes the authentication flow, the docs for authentication should be right there, in the same PR. Separate repos create a gap between "code changed" and "docs should change". That gap is where documentation debt lives. Every guide that tells you to use a separate docs repo is optimizing for the docs team's convenience at the expense of accuracy.

If your docs are already in a separate repo, don't panic. Everything in this guide still applies. But if you're starting fresh, co-locate them. You'll thank me when someone changes an API endpoint and the docs PR is part of the same review.

Group by user task, not by content type. getting-started/ is a user journey. api-reference/ is a content type. I'd love to tell you I'm perfectly consistent about this, but the truth is most real doc structures are a hybrid. The important thing: a new user should be able to look at the folder names and know where to go. If they can't, your IA needs work.

Config files live at the root. Not in a .config/ folder, not inside docs/. Root level. Why? Because every tool expects them there by default, and fighting tool defaults is a waste of your finite time on earth.

The Writing Workflow

Branching

Treat docs PRs like code PRs. Same workflow, same rigor:

git checkout -b docs/update-auth-guide
# write your changes
git add docs/guides/authentication.md
git commit -m "Update auth guide for OAuth2 PKCE flow"
git push origin docs/update-auth-guide

Use a docs/ prefix for documentation branches. Two reasons: it makes filtering your PR list trivial, and you can apply branch-specific CI rules (like running docs checks only on docs/* branches). Small thing, surprisingly useful.

PR Template

Create .github/PULL_REQUEST_TEMPLATE/docs.md:

## What changed
<!-- Brief description of documentation changes -->

## Why
<!-- What triggered this update? Feature change, user feedback, bug fix? -->

## Pages affected
<!-- List the doc pages modified -->

## Checklist
- [ ] Tested all code examples
- [ ] Verified all links work
- [ ] Screenshots are current (if applicable)
- [ ] Reviewed on mobile/responsive view

The "Why" field is the most important part of this template, and the one people skip most often. "Updated the auth docs" tells a reviewer nothing. "Updated auth docs because we switched from API keys to OAuth2 in v3.2" tells them everything. It connects the docs change to the trigger, and six months from now when someone asks "why did we rewrite this page," the answer is right there in the PR.

Automated Quality Checks

This is where docs-as-code stops being a philosophy and starts being a system. Every PR that touches documentation triggers a pipeline of automated checks. Here's each stage, with the configs we actually use.

Stage 1: Spell Checking

The least glamorous check and the one that catches the most embarrassing mistakes:

# .github/workflows/docs.yml (spell check job)
spell-check:
  runs-on: ubuntu-latest
  if: contains(github.event.pull_request.labels.*.name, 'documentation') ||
      contains(join(github.event.pull_request.changed_files), 'docs/')
  steps:
    - uses: actions/checkout@v4
    - uses: streetsidesoftware/cspell-action@v6
      with:
        files: 'docs/**/*.md'
        incremental_files_only: true

Your cspell.json needs a product-specific dictionary. Without one, CSpell will flag every product name, every technical term, and every acronym. After this, your engineers will disable the check within a week:

{
  "version": "0.2",
  "language": "en",
  "words": [
    "your-product-name",
    "OAuth", "PKCE", "webhook", "webhooks",
    "authn", "authz", "kubectl"
  ],
  "ignorePaths": ["docs/assets/**"]
}

Important: Start with incremental_files_only: true. I cannot stress this enough. Running spell check on all files the first time will generate hundreds of findings. Nobody will fix them. The check will become noise. Check only changed files, build the dictionary organically, and clean up old files as you touch them.

Stage 2: Link Validation

Broken links are the cockroaches of documentation. For every one you see, there are ten you don't:

# Link check job
link-check:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: lycheeverse/lychee-action@v2
      with:
        args: >-
          --no-progress
          --exclude-mail
          --exclude 'localhost'
          --exclude '127.0.0.1'
          --exclude 'example.com'
          'docs/**/*.md'
        fail: true

Lychee is fast (Rust-based, concurrent) and handles most edge cases. Your .lychee.toml config handles the rest:

exclude = ["localhost", "127.0.0.1", "example.com"]
accept = [200, 204, 301, 429]
timeout = 10
max_retries = 2

Accept 429 (rate limited) as OK. Some sites aggressively rate-limit automated checkers. Without this, you'll get false failures from GitHub, npm, and basically any popular site. You'll chase ghosts for an hour before you figure out it's not your links that are broken but it's the target servers telling you to slow down. Ask me how I know.

Stage 3: Style Guide Enforcement

This is where consistency happens at scale. Two options, both legitimate:

Option A: Vale (DIY, full control)

# Style lint job
style-lint:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: errata-ai/vale-action@reviewdog
      with:
        files: docs/
        reporter: github-pr-review

Option B: EkLine (managed — includes link checking and style in one action)

# Docs review job
docs-review:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: ekline-io/ekline-github-action@v6
      with:
        content_dir: ./docs
        ek_token: ${{ secrets.EKLINE_TOKEN }}
        github_token: ${{ secrets.GITHUB_TOKEN }}
        reporter: github-pr-review

Full disclosure: EkLine is ours. The honest difference: Vale gives you granular control over every rule and costs nothing. EkLine bundles style, links, and terminology checking into one action and manages the rules for you. If you use EkLine, skip the separate link check job. That is already included. If you use Vale, keep Lychee for links.

Pick based on your situation, not my sales pitch.

The Full Pipeline

Here's the complete workflow file. Copy this, adjust the paths, and you have a working docs-as-code pipeline:

name: Documentation Quality

on:
  pull_request:
    paths:
      - 'docs/**'
      - '*.md'
      - '!README.md'

jobs:
  spell-check:
    name: Spell Check
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: streetsidesoftware/cspell-action@v6
        with:
          files: 'docs/**/*.md'
          incremental_files_only: true

  link-check:
    name: Link Validation
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: lycheeverse/lychee-action@v2
        with:
          args: --no-progress --exclude-mail 'docs/**/*.md'
          fail: true

  style-lint:
    name: Style Guide
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: errata-ai/vale-action@reviewdog
        with:
          files: docs/
          reporter: github-pr-review

  # Optional: build and preview
  build:
    name: Build Preview
    runs-on: ubuntu-latest
    needs: [spell-check, link-check, style-lint]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run build

All three quality jobs run in parallel which is the point. The build step waits for all checks to pass before generating a preview. On most repos, the whole thing finishes in under a minute.

The Human Review Process

Here's the part that trips people up: automated checks don't replace human review. They change what humans review.

What the machine handles:

Spelling errors
Broken links
Style guide violations (headings, terminology, voice, tone)
Formatting consistency

What humans handle:

Is the content actually accurate?
Is the explanation clear to someone who doesn't already understand it?
Are the code examples correct and tested? (Machines can check syntax. They can't check if your example actually solves the problem it claims to.)
Is anything missing?
Does the information architecture make sense?

This separation is the real value of docs-as-code. Not "docs in Git". That's just storage. The value is this: when a reviewer opens a PR and the automated checks have already passed, they know the formatting is clean, the links work, and the style guide is followed. They can focus entirely on whether the content is right.

That's a fundamentally different (and much more useful) review conversation.

Deployment

Once a PR merges, deploy automatically. I'll keep this section short because deployment is well-documented elsewhere and the choices are straightforward:

GitHub Pages (simplest, free):

deploy:
  runs-on: ubuntu-latest
  if: github.ref == 'refs/heads/main'
  needs: [build]
  steps:
    - uses: actions/checkout@v4
    - run: npm run build
    - uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./build

Vercel/Netlify: Connect your repo, get preview URLs on every PR, auto-deploy on merge. Both auto-detect Docusaurus, Next.js, Astro, and most doc frameworks. Setup takes about five minutes. The docs for both platforms cover this better than I can.

Docs platforms (Mintlify, GitBook, ReadMe): They have their own deployment pipelines: push to a branch, they rebuild. Your CI checks still run; they just validate before the platform builds.

Pick one and move on. The deployment step is the least interesting part of this pipeline.

Common Mistakes (The Part You Actually Came Here For)

If you've set up a docs-as-code pipeline before, you probably scrolled straight to this section. I respect that. Here's what goes wrong:

Running all checks on all files from day one. You will generate 500 findings on existing docs. Nobody will fix them. The checks will become noise that everyone ignores. This is the single most common mistake, and I've watched teams make it repeatedly. Start incremental by only checking changed files. Clean up existing docs gradually, file by file, as you touch them for other reasons.

Blocking PRs on warnings. Set style violations to warning for the first month. Let people see them, get used to the feedback loop, understand why the rules exist. Once the team accepts the system, upgrade critical rules to error. If you start with error, you'll get a revolt. I promise.

Separate docs repo without a trigger. If docs live in a separate repo from code, you need a way to signal "the product changed, docs might need updating." A webhook, a GitHub Action that runs on product repo changes, a Slack notification. Something. Anything. Without this signal, the docs repo slowly diverges from reality and nobody notices until a customer complains. This is how documentation debt starts: not with bad writing, but with missing signals.

No code example testing. The most common docs bug isn't a typo or a broken link. It's a code example that doesn't work. The developer copies your snippet, gets an error, and blames your product. Not the docs. If your docs include code snippets, consider extracting and testing them. Tools like mdx-js or custom scripts can help. At minimum, have someone actually run the examples before publishing. Yes, every time.

Ignoring the contributor experience. If your CI takes 10 minutes to run, contributors won't wait. They'll push, context-switch, forget, and your PR will go stale. Keep the docs pipeline under 2 minutes. Run checks in parallel. Use incremental checking. The fastest way to kill a docs-as-code culture is to make the feedback loop slow.

Start Here

If you're setting up docs-as-code from scratch, don't try to build the whole pipeline in a day. Here's the order that works:

Week 1: Set up the repo structure. Add Lychee for link checking. This catches real problems immediately with zero configuration. You'll find broken links you didn't know existed. It's both satisfying and slightly alarming.

Week 2: Add CSpell. Build your product dictionary as you go. Add words when they're flagged incorrectly. The first few days will be annoying. By day five, it's useful.

Week 3: Add style enforcement (Vale or EkLine). Start with a preset style guide. Warnings only. Do not start with errors. I will say this as many times as it takes.

Week 4: Review the findings from week 3. Tune the rules. Disable noisy ones, tighten important ones. Upgrade key rules from warning to error. Now you have a system.

Ongoing: Clean up existing docs gradually. Don't create a "fix all style issues" ticket. That ticket will sit in your backlog for eternity and make everyone sad. Fix issues as you touch files for other reasons. This is how real documentation quality improves: incrementally, consistently, without heroics.

The pipeline is never "done." It evolves with your docs, your team, and your style guide. The important thing is that it exists. And that it runs on every PR, quietly catching the stuff that used to require a human to notice.

That's what docs-as-code actually means. Not "docs in Git." Docs with the same quality guarantees we give to code.

What does your docs pipeline look like? I'd love to compare setups — especially the weird edge cases. Drop a comment or find me at ekline.io.

5 GitHub Actions That Save Our Docs Team Hours Every Week

Bipin Rimal — Wed, 25 Feb 2026 16:22:29 +0000

We're a small startup. And documentation is literally our product — we build tools to help other teams keep their docs accurate. So if our own docs have broken links, inconsistent terminology, or sloppy formatting, that's not just embarrassing. It's the kind of credibility problem that makes potential customers close the tab.

Here's the thing nobody tells you about running a docs-focused company: you become absurdly paranoid about your own documentation. Every broken link feels personal. Every style inconsistency keeps you up at night. But we're a small team — we can't spend our days playing copy editor on every PR.

So we automated the stuff that shouldn't require a human brain. Here are the five GitHub Actions that run on every docs PR in our repo. They're all free for open source, and together they catch the vast majority of issues that used to eat up our review cycles.

1. Catch Broken Links Before They Go Live

The problem nobody wants to admit: You write docs, link to other pages, API references, external resources. You feel good about it. Three months later, half those links are dead. Someone moved a page, a third-party site decided to restructure their entire URL scheme (thanks, I love re-doing work), or you linked to a branch that got merged and deleted.

Broken links are the fastest way to make users distrust your documentation. One dead link and they start wondering what else is wrong. It's like finding a cockroach in a restaurant — you know there are more.

The tool: Lychee — a Rust-based link checker that's fast enough to run on every PR without making you want to throw your laptop.

name: Check Links

on:
  pull_request:
    paths:
      - 'docs/**'
      - '*.md'

jobs:
  link-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check links
        uses: lycheeverse/lychee-action@v2
        with:
          args: >-
            --no-progress
            --exclude-mail
            'docs/**/*.md'
          fail: true

Why Lychee and not the Node-based alternatives: Speed. Lychee is written in Rust and checks links concurrently. On our docs repo (~200 pages), it finishes in under 30 seconds. We tried markdown-link-check first — 3+ minutes. When you're running this on every PR, that difference matters. Nobody wants to wait for CI when they just fixed a typo.

We learned this the hard way: Add a .lychee.toml config to exclude URLs that are expected to fail in CI. We spent a very confusing afternoon debugging "broken" links that were just localhost examples in code snippets:

exclude = [
  "localhost",
  "127.0.0.1",
  "example.com"
]

Time saved: About 2 hours per week of "why does this link 404" tickets. Which, honestly, were the most soul-crushing tickets to deal with.

2. Enforce Your Style Guide Automatically

The problem: Your style guide says "use second person" and "prefer active voice." Your docs say "the configuration can be completed by the user." Everyone knows the rules. Nobody catches everything. Including you — especially at 4pm on a Friday.

Style guide violations are like dishes in the sink. Nobody notices one. But after a month, your kitchen is a health hazard and nobody wants to cook. After a year, your docs read like they were written by 20 different people — because they were.

The tool: Vale — a prose linter with presets for Google, Microsoft, and other style guides. Think ESLint, but for words.

name: Prose Lint

on:
  pull_request:
    paths:
      - 'docs/**'

jobs:
  vale:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Vale lint
        uses: errata-ai/vale-action@reviewdog
        with:
          files: docs/
          reporter: github-pr-review
          vale_flags: "--minAlertLevel=warning"

The key configuration is the .vale.ini file in your repo root:

StylesPath = .vale/styles
MinAlertLevel = warning

[docs/*.md]
BasedOnStyles = Google

This uses Google's style guide out of the box. Want Microsoft's instead? Change Google to Microsoft. Want your own custom rules? Create YAML files in .vale/styles/YourCompany/. Fair warning: you will go down a rabbit hole. It's kind of fun, though.

Honest caveat: Vale is powerful but it has a learning curve. Writing custom rules is its own skill, and it took us a few iterations to get our config dialed in without drowning in false positives. If you want something that works out of the box with less yak-shaving, that's where tools like EkLine come in (see #5). But if you're the type who enjoys fine-grained control and building your own system, Vale is the gold standard. No question.

Time saved: About 1-2 hours per week of leaving "please change this to active voice" comments. My least favorite type of review comment to leave, and probably everyone's least favorite to receive.

3. Kill Typos Without a Human Proofreader

The problem: Traditional spell checkers and technical writing are mortal enemies. They flag kubectl, OAuth, GraphQL, and every product name as errors. So people turn them off. And then actual typos ship. And then you're the company whose security doc says "authetication."

(Don't laugh. We caught that one in a PR. Twice.)

Documentation with typos reads as careless. And in code examples, a typo isn't just embarrassing — it means the example literally doesn't work. A developer copies your snippet, gets an error, and blames your product. Not the typo. Your product.

The tool: CSpell — a spell checker that actually understands technical terminology, so it won't flag every third word in your API docs.

name: Spell Check

on:
  pull_request:
    paths:
      - 'docs/**'

jobs:
  cspell:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Spell check
        uses: streetsidesoftware/cspell-action@v6
        with:
          files: 'docs/**/*.md'
          incremental_files_only: true

The magic is in cspell.json, where you define your product dictionary:

{
  "version": "0.2",
  "language": "en",
  "dictionaries": ["tech-terms"],
  "dictionaryDefinitions": [
    {
      "name": "tech-terms",
      "path": ".cspell/tech-terms.txt",
      "addWords": true
    }
  ],
  "words": [
    "EkLine", "ekline",
    "Docusaurus", "Mintlify", "GitBook",
    "devops", "cicd"
  ],
  "ignorePaths": [
    "node_modules/**",
    "*.min.js"
  ]
}

Do this or you'll hate yourself: Use incremental_files_only: true to only check changed files. We made the mistake of running it on everything the first time. Hundreds of findings. Nobody wanted to touch it. It sat in a ticket for three weeks before we wised up and switched to incremental-only. Build the dictionary over time — don't try to boil the ocean.

Time saved: About 30 minutes per week, plus the priceless benefit of never shipping "authetication" in a security doc. Again.

4. Stop Docs PRs From Going Stale

The problem: Someone opens a docs PR. Reviewer is busy. A week passes. The contributor moves on to something else. The PR sits for two months, accumulates merge conflicts, and eventually gets closed with a sad little "closing due to inactivity" comment.

We've all been on both sides of this. It's demoralizing for contributors, and for small teams it creates this invisible drag — every time you open the PR list, you have to mentally re-process "is this still relevant?" for PRs that should have been closed weeks ago.

The tool: Stale — GitHub's official action for managing inactive issues and PRs. Simple, effective, slightly passive-aggressive in the best way.

name: Stale Docs PRs

on:
  schedule:
    - cron: '0 9 * * MON'  # Every Monday at 9am

jobs:
  stale:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/stale@v9
        with:
          repo-token: ${{ secrets.GITHUB_TOKEN }}
          stale-pr-message: >
            This PR has been inactive for 14 days.
            If the changes are still needed, please rebase
            and request a re-review. Otherwise, it will be
            closed in 7 days.
          stale-pr-label: 'stale'
          days-before-pr-stale: 14
          days-before-pr-close: 21
          only-labels: 'documentation'

Why this matters more than it sounds: Before we added this, our PR list was a graveyard. Eight open PRs, four of them from two months ago. Every Monday's standup included someone asking "should we close these?" and nobody committing to it. Now the bot handles it. The mental overhead just... disappeared.

One thing we got wrong at first: Set only-labels: 'documentation' so this only affects docs PRs. Code PRs have different lifecycle expectations. We didn't scope it initially and accidentally auto-closed a feature PR that was waiting on a design review. That was a fun conversation.

Time saved: About 1 hour per week of PR grooming and "is this still needed?" purgatory.

5. Automated Docs Review With Inline PR Comments

The problem: Actions #1-3 each solve one piece of the puzzle. But running three separate actions means three separate configurations, three sets of output to parse, and no single view of "how's this PR's documentation quality, overall?"

What if one action could check your style guide, validate links, flag terminology issues, and give you a quality score — all as inline PR comments, right on the lines where the issues are?

The tool: EkLine — full disclosure, this is ours. I'll keep this brief and honest.

name: Documentation Review

on:
  pull_request:
    paths:
      - 'docs/**'
      - '*.md'

jobs:
  docs-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: EkLine Docs Review
        uses: ekline-io/ekline-github-action@v6
        with:
          content_dir: ./docs
          ek_token: ${{ secrets.EKLINE_TOKEN }}
          github_token: ${{ secrets.GITHUB_TOKEN }}
          reporter: github-pr-review

It analyzes changed files and leaves inline review comments directly on the PR — style guide compliance, link validity, terminology consistency, quality score per file. Not a wall of CI output. Comments on the exact lines where the issues are.

When to use EkLine vs. the DIY stack:

	DIY Stack	EkLine
Setup time	Hours (configure each tool)	Minutes (one action, managed rules)
Customization	Full control over every rule	Presets + custom config
Cost	Free (all open source)	Free for public repos, paid for private
Output	Separate CI logs per tool	Unified inline PR comments
Maintenance	You maintain configs + updates	Managed
Best for	Teams who want granular control	Teams who want it working now

We obviously eat our own dogfood — EkLine runs on every PR we open. But the honest truth is: if you enjoy building your own toolchain and you want total control, the DIY stack (Vale + Lychee + CSpell) is excellent. If you're a small team and you'd rather spend your time writing docs than configuring linters, that's what we built EkLine for.

Time saved: About 3-4 hours per week of mechanical review work.

The Combined Workflow

You don't have to pick just one. Here's a minimal combined workflow:

name: Docs Quality

on:
  pull_request:
    paths:
      - 'docs/**'
      - '*.md'

jobs:
  spell-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: streetsidesoftware/cspell-action@v6
        with:
          files: 'docs/**/*.md'
          incremental_files_only: true

  link-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: lycheeverse/lychee-action@v2
        with:
          args: --no-progress --exclude-mail 'docs/**/*.md'
          fail: true

  docs-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ekline-io/ekline-github-action@v6
        with:
          content_dir: ./docs
          ek_token: ${{ secrets.EKLINE_TOKEN }}
          github_token: ${{ secrets.GITHUB_TOKEN }}
          reporter: github-pr-review

The three jobs run in parallel. Most PR builds finish in under a minute. Contributors get feedback before a human reviewer even opens the PR.

What This Actually Looks Like in Practice

Before we set this up, our docs PR review went like this:

Contributor opens PR
Waits 1-3 days for reviewer (we're a small team, we're busy)
Reviewer leaves 8 comments — 3 about style, 2 about links, 1 typo, 2 about actual content
Contributor fixes, pushes again
Reviewer re-reviews (another day)
Merged on day 5

Now:

Contributor opens PR
Automated checks run in 60 seconds
Contributor sees inline feedback, fixes mechanical issues themselves
Reviewer sees clean PR, focuses on one question: "Is this content accurate and helpful?"
Merged same day

The biggest shift isn't time saved — it's who fixes what. Contributors fix their own mechanical issues because the feedback is instant and specific. It's not a person telling them "you got this wrong." It's a bot, and somehow that stings less. Reviewers stop being the grammar police and start being the content experts they were hired to be.

That's the real win. Not the hours. The sanity.

Start With One, Add More Later

If you're starting from zero, don't set up all five on day one. You'll spend more time configuring tools than writing docs, and that defeats the entire point.

Here's the order I'd recommend:

Start with Lychee (link checking). Broken links are the most common and most damaging docs issue. Basically zero configuration. Immediate value.
Add CSpell once you've built a product dictionary. This takes about a week of "add to dictionary" clicks before it stops being annoying and starts being useful.
Add Vale or EkLine when you have a style guide you actually want to enforce. If you don't have a style guide yet, pick Google's and customize from there.
Add Stale when your PR backlog grows beyond what you can track in your head. For us, that was about PR number six.

Each one is useful on its own. Together, they're a system. But a system you build up over time — not one you configure in a weekend and then never touch again (because that system will rot just like your docs).

What's in your docs CI pipeline? We're always looking for new tools to try. Drop a comment or reach out — we genuinely want to know what's working for other teams.

About the author: Bipin works on documentation tooling at EkLine — a small team building documentation quality tools. He's interested in how teams scale documentation quality without scaling review burden. Check out our public repos at github.com/ekline-io/ekline-github-action.

Automating Documentation Review in Your CI/CD Pipeline

Bipin Rimal — Fri, 13 Feb 2026 12:34:59 +0000

You lint your code. You run tests. You check for security vulnerabilities.

But what about your documentation?

Most teams treat docs as second-class citizens in CI/CD. Code gets automated quality gates; docs get... a human reading them whenever they have time.

Here's how to change that.

The Problem: Documentation Review is a Bottleneck

Every docs PR in our repo sat waiting for review. Someone had to manually check:

Are headings capitalized correctly?
Did the author use our terminology ("click" not "select")?
Are all the links still valid?
Is the structure consistent with other pages?

This was tedious for reviewers and slow for contributors. Engineers would submit docs, wait days for feedback, then get a list of nitpicky style fixes.

We decided to automate the mechanical stuff.

What We Automated

Check	Before	After
Style guide compliance	Manual review	Automated
Broken links	Occasional spot checks	Every PR
Terminology consistency	"I think we use X?"	Enforced
Heading format	Manual review	Automated
Quality metrics	None	Per-file scores

The Setup: GitHub Actions + EkLine

We use EkLine for automated docs review. Here's our workflow:

name: Documentation Review

on:
  pull_request:
    paths:
      - 'docs/**'
      - '*.md'

jobs:
  docs-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: EkLine Docs Review
        uses: ekline-io/ekline-github-action@v6
        with:
          content_dir: ./docs
          ek_token: ${{ secrets.EKLINE_TOKEN }}
          github_token: ${{ secrets.GITHUB_TOKEN }}
          reporter: github-pr-review

That's it. When someone opens a PR that touches documentation, EkLine:

Analyzes the changed files against our style guide
Checks all links
Validates terminology
Leaves inline comments directly on the PR

What the Feedback Looks Like

Instead of a wall of linter output in CI logs, contributors get comments exactly where issues are:

The feedback is actionable: "Define 'MCP', if it's unfamiliar to the audience." with a suggestion to fix it.

Configuring Your Style Rules

EkLine comes with presets (Google, Microsoft), but you can customize:

# .ekline/config.yaml
rules:
  headings:
    capitalization: sentence-case
  voice:
    prefer: active
  terminology:
    banned:
      - utilize  # use "use"
      - leverage # use "use"
      - click    # use "select"
    required:
      - API      # not "api" or "Api"

Results After 3 Months

Metric	Before	After
Avg. review cycles per docs PR	2.4	1.4
Time to first feedback	1-3 days	Instant
Style-related review comments	~60%	~10%
Broken links shipped	Monthly	Rare

The biggest win wasn't efficiency—it was contributor confidence. Engineers now get instant feedback, fix issues themselves, and submit cleaner PRs. They're not waiting days just to learn they used the wrong heading style.

Bonus: Automating the "What Needs Updating?" Problem

Automated review catches issues in what you submit. But there's a harder problem: knowing what should be submitted after a product change.

EkLine also has a Docs Agent that addresses this. You can prompt it:

"The user invitation flow changed from 2 steps to 3 steps"

And it will:

Scan your docs repo for all files mentioning invitations
Draft updated content
Create a PR with the changes

This shifts documentation maintenance from "hope someone remembers" to "tell the agent what changed." We're still rolling this out, but early results show it dramatically reduces docs drift.

Alternatives to Consider

If EkLine doesn't fit your needs:

Vale — The underlying linter many tools use. More DIY, but very flexible.
alex — Focused on inclusive language checking.
markdownlint — Basic Markdown formatting rules.

The difference with EkLine is the GitHub integration (inline PR comments) and managed style guide configs. If you want to build your own setup, Vale is excellent.

Should You Automate Docs Review?

Yes, if:

Multiple people contribute to documentation
You have (or want) a style guide
Review cycles are slowing down releases
You're already using docs-as-code

Maybe not, if:

Solo writer on a small project
Docs are in Confluence/Notion (no Git integration)
Your review process works fine

Getting Started

Sign up at ekline.io — free for public repos, 30-day trial on Standard ($50/user/month)
Add the GitHub Action to your repo
Open a PR with docs changes
See the automated review

Full setup guide: docs.ekline.io

What's in Your Docs CI?

I'm curious what other teams are doing for documentation quality. Are you:

Running any automated checks?
Using different tools?
Still doing everything manually?

Drop a comment—I'd love to learn from your setup.

Bipin works on documentation tooling at EkLine. He's interested in how teams scale documentation quality without scaling review burden.

Your Documentation is Lying to Your Users

Bipin Rimal — Fri, 13 Feb 2026 12:32:51 +0000

Let me be direct: your documentation is probably lying to your users right now.

Not maliciously. Not intentionally. But lying nonetheless.

That endpoint you deprecated three months ago? Still documented as active. That config flag you renamed in v2.3? Still showing the old name. That "quick start" guide that takes 47 steps because your product evolved?

Every day, developers hit your docs, follow instructions that no longer work, and quietly conclude your product is broken. They don't file a bug. They don't complain. They just leave.

The Math Doesn't Work

Here's the uncomfortable reality most teams avoid:

Documentation decays faster than you can maintain it.

Think about it. Every feature ship, every API change, every UI update, every renamed variable creates potential doc drift. In a healthy engineering org shipping weekly? That's 50+ potential documentation landmines per year. Per product.

Now look at your docs team. One person? Two? Part-time contributors who'd rather be coding?

The math doesn't work. It never did.

"We'll Update Docs Before Release"

Every team says this. Almost none do it consistently.

Why? Because documentation updates compete with shipping features. And shipping features wins. Every time.

This isn't a discipline problem. It's a systems problem.

Your CI catches code bugs before merge. Your tests catch regressions. Your linters catch style violations.

What catches documentation drift? A customer complaint three months later? A support ticket from someone who wasted an hour on outdated instructions?

That's not a system. That's hope.

The Bug Reframe

Here's what changed my thinking: treat outdated documentation as a bug.

Not a "nice to have." Not a "we'll get to it." A bug. With the same urgency you'd give a production incident.

Because that's what it is. When your docs say one thing and your product does another, that's a defect in your customer experience. It's a reliability issue.

Bugs get tracked. Bugs get prioritized. Bugs get fixed.

Documentation drift? It just... accumulates. Until someone notices. Which is usually a customer. Who's now frustrated.

What Actually Works

After watching this pattern repeat across teams, here's what I've seen work:

1. Automate the detection, not just the writing

The hard part isn't writing docs. It's knowing when docs need updating.

When your product changes, something should flag which documentation is now potentially wrong. Not "maybe we should check the docs." A specific alert: "This PR modified the authentication flow. These 4 doc pages reference authentication."

2. Put docs in the same workflow as code

Docs-as-code isn't just a storage strategy. It's a workflow strategy.

If docs live in the same repo, reviewed in the same PRs, tested in the same CI—they get the same attention as code. Not because people suddenly care more about docs. Because the system treats them equally.

3. Make "done" include documentation

This is cultural, but systems can enforce it.

A feature isn't shipped until the docs are updated. A breaking change isn't merged until the migration guide exists. Not as a suggestion. As a gate.

The Tooling Gap

For code quality, we have: linters, formatters, type checkers, test frameworks, security scanners, dependency auditors.

For documentation quality, most teams have: a human reading it when they have time.

That gap is why docs rot faster than code.

The fix isn't more humans. It's applying the same thinking we already apply to code: automated checks, continuous validation, systematic enforcement.

Style guide violations? Flag them automatically. Broken links? Catch them in CI. Terminology inconsistency? Enforce it the same way you enforce code style.

This isn't complicated. We just haven't bothered to apply existing patterns to documentation.

The Real Cost

"Our docs are a little out of date" sounds minor.

Here's what it actually costs:

Support tickets for problems the docs created
Lost deals when prospects can't complete your quick start
Churn from users who concluded your product doesn't work
Engineering time answering questions that docs should handle
Reputation damage in every "your docs are wrong" GitHub issue

Most teams never connect these costs to documentation. They're too diffuse. Too delayed.

But they're real. And they compound.

A Challenge

Here's something you can do in 10 minutes:

Pick your most important user journey (signup, first API call, basic integration)
Follow your own docs as if you've never seen your product
Note every place where instructions don't match reality

Most teams find 3-5 issues. In their most important flow. That users hit every day.

That's not a documentation problem. That's a customer experience bug hiding in plain sight.

What I Use

Full disclosure: I use EkLine for automated docs review. It runs in CI, flags style issues, catches broken links, and tells me when product changes affect documentation.

It's not the only option. Vale is excellent if you want to build your own system. The point isn't the tool—it's treating documentation with the same rigor we apply to code.

Whatever you use, the first step is the same: stop treating documentation as a writing problem. Start treating it as a systems problem.

The writing was never the hard part.

What's the oldest lie in your documentation? I'm genuinely curious—drop a comment. No judgment. We've all been there.