DEV Community: EkLine.io

What Wrong Docs Cost Test Automation Teams

EkLine.io — Thu, 21 May 2026 15:00:27 +0000

You know the feeling. You copy a code example from the official docs, wire it into your test suite, and everything passes. Green across the board. Three months later, the framework ships a major version, that example uses a deprecated command, and suddenly 200 tests across 50 teams are failing on Monday morning.

Nobody changed the tests. Nobody changed the application. The docs were wrong, and the tests were built on them.

In test automation, a wrong code example does not break one test. It breaks every test that was modeled after it.

The ecosystem is bigger than you think

Test automation frameworks are infrastructure now, not niche tools.

microsoft / playwright

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

🎭 Playwright

Documentation | API reference

Playwright is a framework for web automation and testing. It drives Chromium, Firefox, and WebKit with a single API — in your tests, in your scripts, and as a tool for AI agents.

Get Started

Choose the path that fits your workflow:

Best for	Install
Playwright Test	End-to-end testing	`npm init playwright@latest`
Playwright CLI	Coding agents (Claude Code, Copilot)	`npm i -g @playwright/cli@latest`
Playwright MCP	AI agents and LLM-driven automation	`npx @playwright/mcp@latest`
Playwright Library	Browser automation scripts	`npm i playwright`
VS Code Extension	Test authoring and debugging in VS Code	Install from Marketplace

Playwright Test

Playwright Test is a full-featured test runner built for end-to-end testing. It runs tests across Chromium, Firefox, and WebKit with full browser isolation, auto-waiting, and web-first assertions.

Install

npm init playwright@latest

Or add manually:

npm i -D @playwright/test
npx playwright install

Write a test

import { test, expect

…

View on GitHub

cypress-io / cypress

Fast, easy and reliable testing for anything that runs in a browser.

Documentation | Changelog | Roadmap

The web has evolved. Finally, testing has too.

Fast, easy and reliable testing for anything that runs in a browser.

Join us, we're hiring.

What is Cypress?

Installing

Install Cypress for Mac, Linux, or Windows, then get started.

npm install cypress --save-dev

yarn add cypress --dev

pnpm add cypress --save-dev

Contributing

- develop branch

Please see our Contributing Guideline which explains repo organization, linting, testing, and other steps.

License

This project is licensed under the terms of the MIT license.

Badges

Configure a badge for your project's README to show your test status or test count in the Cypress Cloud.

Or let the world know your project is using Cypress with the badge below.

[![Cypress.io](https://img.shields.io/badge/tested%20with-Cypress-04C38E.svg)](https://www.cypress.io/)

View on GitHub

Framework	GitHub Stars	Dependent Projects
Playwright	85,100+	451,000+
Cypress	49,600+	1,500,000+

Playwright publishes documentation across four languages: Node.js, Python, Java, and .NET. That is four times the surface area for documentation drift. Cypress has shipped 389 releases since its inception, and each release can deprecate commands, change default behaviors, or introduce new APIs.

A code example written for Cypress 12 may use cy.intercept() patterns that behave differently in Cypress 15. The example still runs. It just does not do what you expect.

The real cost, by the numbers

Here is where stale docs hit your team's budget, velocity, and trust.

Test maintenance eats 40-60% of all testing effort

The Capgemini World Quality Report consistently finds that test maintenance consumes 40-60% of total testing effort. That is not writing new tests. That is fixing existing ones that broke because something changed underneath them.

When a QA engineer fixes a failing test, the first thing they check is the framework docs. If the docs still show the old pattern, the engineer cannot tell whether the test is wrong or the framework changed. They burn time debugging a problem that accurate documentation would have prevented.

The Katalon State of Software Quality Report 2025 found that only 11% of QA teams have reached an optimized level of test automation maturity. 56% of QA teams report they cannot keep up with testing demands. Documentation that adds friction instead of removing it makes this gap wider.

72% of developers abandon tools over bad docs

The Postman 2023 State of the API Report found that 72% of developers have abandoned an API due to poor documentation. 54% cite documentation as the number one factor when evaluating a tool.

The Stack Overflow Developer Survey 2023 found that 90.36% of developers use technical documentation as their primary learning resource. For test frameworks competing for adoption (Cypress vs. Playwright vs. Selenium vs. AI-powered tools like Mabl and Testim), your docs are the product evaluation. A developer who hits a broken quickstart example does not file a bug. They try the other framework.

CI pipeline failures: the cost nobody tracks

Each engineering-escalated support ticket costs $150 to $250 (DevRelCon / MetricNet). For a framework with thousands of users, a single stale example that generates 100 support tickets costs $15,000 to $25,000 in direct support alone. The real cost is the engineering hours spent debugging a documentation problem instead of shipping features.

What this looks like in your codebase

Your testing framework docs show this page object pattern:

// Cypress 12 page object pattern (outdated)
class LoginPage {
  visit() {
    cy.visit('/login')
  }

  fillUsername(username) {
    cy.get('#username').type(username)
  }

  fillPassword(password) {
    cy.get('#password').type(password)
  }

  submit() {
    cy.get('form').submit()
  }
}

But Cypress 15 recommends the App Actions pattern with cy.session() for authentication:

// Cypress 15 recommended pattern
Cypress.Commands.add('login', (username, password) => {
  cy.session([username, password], () => {
    cy.visit('/login')
    cy.get('[data-testid="username"]').type(username)
    cy.get('[data-testid="password"]').type(password)
    cy.get('[data-testid="submit"]').click()
    cy.url().should('include', '/dashboard')
  })
})

Both compile. Both run. But the first pattern creates a new browser session for every test, making the suite 3-5x slower. A team that follows the old docs builds 500 tests on the slow pattern before discovering the performance problem. Rewriting 500 tests is not a bug fix. It is a quarter of engineering time.

Three things that close the gap

1. Automated review on every PR. When framework code changes, check if documentation references the changed commands, selectors, or configuration options. Flag stale examples before they merge. For a framework shipping 30+ releases per year, manual review cannot keep pace.

2. Version-aware example validation. Your documentation linting should know which framework version each example targets. An example using cy.server() (removed in Cypress 12) or page.waitForNavigation() (deprecated in Playwright) should trigger a warning in the PR where the deprecation happens, not after a user reports it.

3. Cross-language freshness tracking. For frameworks like Playwright that publish docs in four languages, track which language variants have been updated when the underlying API changes. A Node.js example that gets updated while the Python equivalent stays stale creates an inconsistency that users of the less-maintained language will hit first.

The bottom line

If your testing framework documentation is the first thing a QA engineer reads when evaluating your tool, it needs the same quality bar as the framework itself.

How does your team keep test framework docs in sync? Drop your workflow in the comments. I am genuinely curious whether anyone has solved the version drift problem across multiple language SDKs.

If your team has this problem, where stale code examples in docs are creating downstream test failures, EkLine automates documentation review in your GitHub PR workflow. It catches stale code examples, broken links, and style violations before they reach developers. See how it works.

An Open Banking API Is a Contract. Your Docs Are the Contract Surface.

EkLine.io — Thu, 14 May 2026 13:39:29 +0000

Strip the acronyms off open banking and what you have is a small, boring promise.

A bank says to a third-party app: if you bring me a customer who agreed to share their data, I will hand you that data in a predictable shape, through a predictable door, using a predictable key, and I will tell you in a predictable way when something goes wrong.

Four predictable things. That is the whole deal.

When all four hold, an app can read a customer's transactions and tell them they spend too much on coffee. When even one of them slips, calls still return 200, dashboards stay green, and the data flowing through is quietly wrong. The contract has broken silently, and the only place it can break is in the documentation that was supposed to describe the contract.

This post is about the four predictabilities, where they leak, and why your docs are the only place to catch the leak before a regulator does.

The Contract, in Four Parts

Part 1: a predictable SHAPE for the data
Part 2: a predictable PERMISSION flow
Part 3: a predictable AUTHORIZATION credential
Part 4: a predictable ERROR vocabulary

That is the entire open banking contract from a developer's point of view.

The UK Open Banking Standard and the PSD2 RTS in the EU both encode the same four parts in different words. Your bank's docs are how you, the developer building on top of the bank, learn what shape, what flow, what credential, and what error codes the bank chose inside the room the regulation gave it.

When the docs and the running API agree, the contract holds. When they disagree, here is what breaks.

Drift 1: The Shape Drifts

Documented response has 12 fields. Production now returns 14.

// Documented
{
  "transaction_id": "...",
  "amount": "...",
  "currency": "...",
  "booked_at": "...",
  "description": "...",
  "counterparty": { ... }
  // ... 6 more documented fields
}

// Production today
{
  "transaction_id": "...",
  "amount": "...",
  "currency": "...",
  "booked_at": "...",
  "description": "...",
  "counterparty": { ... },
  "merchant_category_code": "5814",   // NEW, undocumented
  "scheme_id": "FPS-2026-..."         // NEW, undocumented
  // ... 6 more documented fields
}

The app reading this ignores the two unknown fields. It still works. But the budgeting category it shows the customer is now derived from a heuristic the app wrote two years ago, when the actual merchant category code is sitting unused in the response. The app cannot use what the docs do not say is there.

Drift 2: The Permission Drifts

Docs list 5 consent scopes. Production added a 6th, required for the standing-orders endpoint.

The app requests the documented 5. The bank's authorization server returns a token. The token works for the four endpoints the app uses. The standing-orders endpoint returns a 200 with an empty array.

The app interprets "empty" as "this customer has no standing orders." The customer has six. They call support to ask why their rent payment is missing.

Empty data and missing-permission data look identical to a client unless the docs say otherwise. The docs were the only place the new scope could have been announced.

Drift 3: The Credential Drifts

Docs describe OAuth 2 with bearer tokens. Production migrated higher-value endpoints to mutual TLS.

GET /accounts/{id}/balance       → bearer token works
POST /payments                   → mTLS required, bearer token = TLS handshake error

The app, holding only a bearer token, can read balances fine. The first time the customer initiates a payment, it fails with a TLS error the app never expected. The on-call engineer spends two hours hunting a network problem that does not exist. The actual problem is that the docs described one credential and production now requires two.

Drift 4: The Errors Drift

Docs say 429 Too Many Requests means "you are sending requests too fast."

Production has started returning 429 for a second case: "the customer revoked consent in the last 60 seconds and our consent cache is still warm."

# What the docs imply
if response.status == 429:
    sleep(retry_after)
    retry()

Three retries later, the bank's actual rate limiter trips and bans the app's IP for an hour. One customer revoked consent. Now the app cannot serve any of its customers using that bank, because 429 grew a second meaning the docs never described.

Why the Docs Are the Only Place to Catch This

A test environment catches a broken endpoint. Monitoring catches an outage. A regulator catches a serious incident, eventually.

None of them catch silent contract drift. Silent drift looks identical to a healthy system from every observation point except one: a developer reading the docs and finding they describe a different system than the one answering when called.

The Postman 2025 State of the API Report found 55% of teams cite documentation gaps as their top collaboration challenge. In open banking, "collaboration" includes the regulator. The FCA and EBA both require documented behavior to match production behavior, because a third-party app cannot comply with rules it cannot read.

Three Rules That Follow

If the docs are the contract surface, then changes to the API are changes to the contract, and:

The schema in the docs is the schema in production. Generated reference docs are not a nice-to-have in this niche. Hand-edited reference is a contract risk.
Every consent scope and every error code is documented before it is enforced. If a scope becomes required Tuesday, the docs say so Monday.
Deprecations ship with a date and an alternative. Silent deprecations are silent contract breaks.

That is the whole post in three lines.

The One-Sentence Version

An open banking API is a four-part contract, the docs are the contract, and when the two disagree the only people who notice are the customers calling support to ask why their money looks wrong.

EkLine checks every doc change against the live spec, the consent model, and the published error catalog so the contract surface stays honest.

What Wrong API Docs Cost Identity Verification Teams

EkLine.io — Tue, 12 May 2026 19:29:30 +0000

You have been there. You are integrating a KYC endpoint, the docs say to pass three watchlist sources, your request gets a clean 200 back, and everything looks fine. Two months later, compliance flags the integration because a fourth watchlist source became required and nobody updated the docs. The API never rejected the request. It just silently ran an incomplete screening.

This is not a hypothetical. It is the kind of thing that costs identity verification teams real money.

The Numbers Behind the Problem

Global identity fraud costs now exceed $50 billion annually. Synthetic identity fraud alone accounts for $20 to $40 billion in global losses each year. In the first half of 2025, 8.3% of all digital account creations were flagged as suspected fraud.

Identity verification APIs are the front line. Platforms like Socure's ID+ platform, Jumio, and Alloy let teams call a single endpoint for KYC checks, fraud scoring, document verification, and watchlist screening. But the defense only works if the integration is correct. And the integration is only as correct as the documentation guiding it.

Here is where things break down.

1. Compliance Fines from Stale Docs

Sixty percent of fintechs paid at least $250,000 in compliance fines last year. Ninety-three percent struggle to satisfy compliance requirements. In many of those cases, the root cause was not a code bug. It was stale documentation.

Consider this request body for a multi-module identity check:

{
  "modules": ["kyc", "fraud", "watchlist"],
  "config": {
    "consentObtained": true,
    "watchlistSources": ["ofac", "pep", "adverse_media"]
  }
}

If watchlistSources was recently expanded to require sanctions_consolidated but the docs still list the old three values, every integration built from those docs is running an incomplete screening. The API returns 200. The check "passes." But the compliance record is now inaccurate.

PCI DSS requires documentation of data flows and security controls. KYC/AML regulations require auditable verification trails. When the docs describing these flows do not match the running code, the audit trail has a hole in it. And auditors are very good at finding holes.

2. Integration Delays That Multiply

The Postman 2025 State of the API Report found that 55% of API teams cite documentation gaps as their top collaboration challenge. In identity verification, the impact is amplified because a single integration typically touches multiple modules at once.

A typical identity verification flow looks like this:

Module	What It Does	What Breaks with Bad Docs
Identity Resolution	Matches user data to authoritative sources	Wrong field mappings, missed required params
Fraud Scoring	Returns risk scores with reason codes	Misinterpreted score ranges, stale thresholds
Document Verification	Validates government IDs	Unsupported doc types silently fail
Watchlist Screening	Checks OFAC, PEP, adverse media	Incomplete source lists, missed screening
Decision Engine	Routes pass/fail/review decisions	Logic built on outdated score interpretations

When a developer hits an undocumented edge case in one module, the entire integration stalls. And organizations using well-documented, API-driven verification processes reduced compliance costs by 47% and improved verification accuracy by 31%, according to the KYC Benchmark Report. The difference is not the technology. It is whether the team integrating the technology can trust what the docs say.

3. Fraud That Slips Through Undocumented Changes

Identity verification APIs evolve constantly. New fraud vectors emerge, scoring models get retrained, risk thresholds shift. When those changes ship without corresponding documentation updates, downstream teams do not adjust their decision logic.

Socure's Sigma Identity Fraud module can capture up to 90% of fraud in the riskiest 3%. That precision depends on integrators correctly interpreting score ranges, reason codes, and threshold recommendations. If a model update shifts what a score of 0.7 means, but the docs still describe the old interpretation, fraud teams will make decisions on stale logic.

Financial services fraud losses reached $12.5 billion in 2024, a 25% increase over the previous year. Not all of that traces to documentation. But every undocumented API change creates a window where fraud scoring, decision routing, or compliance checks may operate on wrong assumptions.

The Documentation Stack That Actually Matters

Identity verification APIs carry a heavier documentation burden than most fintech APIs. The minimum viable docs must cover:

Authentication and scopes: Which API keys access which modules, what permissions each scope grants
PII handling: How personal data is encrypted in transit, masked in logs, retained or purged per regulation
Compliance mappings: Which endpoints satisfy which regulatory requirements (KYC, AML, OFAC screening)
Versioning and deprecation: When endpoints change, what breaks, and how to migrate
Error codes with remediation: Not just 400 Bad Request but missing required field: consentObtained, see migration guide v4.2

When any layer in this stack drifts from the running code, the cost shows up as a compliance finding, a failed integration, or a fraud event that should have been caught.

Treating Docs Like Code

The teams that avoid these costs treat documentation the way they treat code: it gets tested in CI, it gets reviewed in PRs, and it gets flagged when it drifts from the source of truth.

Here is what that looks like as a linting rule:

# Example: CI rule for identity verification docs
rules:
  - id: kyc-endpoint-versioning
    description: KYC endpoints must document version and deprecation date
    pattern: "/api/v[0-9]+/(kyc|verify|screening)"
    require:
      - version_header
      - deprecation_notice
      - migration_guide_link

Running documentation checks in the same pipeline that tests the API means a new endpoint parameter cannot ship without a corresponding docs update. A deprecated field cannot linger in production docs past its removal date. A compliance-critical module cannot change its behavior without a changelog entry.

This is not a tooling problem. It is a workflow problem. The documentation review needs to sit in the same pipeline as the code review, not in a separate wiki that gets updated "when someone has time."

The Bottom Line

Identity verification documentation is not a developer convenience. It is a compliance control, a fraud prevention layer, and an integration reliability guarantee.

When the docs are wrong, the integration is wrong. When the integration is wrong, the verification is incomplete. And when the verification is incomplete, the cost shows up as a fine, a fraud loss, or a partner who takes their integration timeline from weeks to months.

If your identity verification docs drift between releases, EkLine catches the gap before your auditor does.

What is the worst documentation gap you have hit during an API integration? Stale field names, missing error codes, undocumented breaking changes? Drop your war stories in the comments.

Your Support Tickets Are a Documentation Backlog in Disguise

EkLine.io — Fri, 08 May 2026 14:32:29 +0000

You know the feeling. You are deep in a debugging session, finally making progress on that memory leak, and a Slack notification pulls you out. A customer cannot figure out how to configure SSO with your product. You write a detailed, thoughtful response. You resolve the ticket. You go back to your code. Three days later, a different customer asks the exact same question. A different engineer writes a slightly different answer. The docs never change.

This is not a support problem. It is a documentation deployment problem.

The Numbers

The cost gap between support-assisted and self-service resolution is wide:

Resolution Channel	Cost Per Ticket
Agent-assisted (B2B avg)	$18 - $35
Self-service / docs	$1 - $4

If 30% of your tickets are questions your docs should already answer, you are spending thousands per quarter on a problem that documentation updates would eliminate. Companies that systematically turn support interactions into documentation updates reduce ticket volume by 20 to 30% on the topics they address.

The Broken Loop

Support platforms like Pylon, Intercom, Plain, and Thena are good at managing conversations. Tagging, routing, SLA tracking, AI summaries. What they have not solved is the feedback loop: when a ticket reveals a documentation gap, who updates the docs?

Here is what the ticket lifecycle looks like in most organizations:

Customer hits a documentation gap
Customer files a support ticket
Support agent writes a one-off answer
Ticket closes
Documentation stays unchanged
Next customer hits the same gap
goto 2

Harvard Business Review research found that reducing customer effort is the single strongest driver of loyalty. Yet most documentation teams operate reactively, fixing pages only after complaints pile up.

Three Components of the Fix

The support-to-docs loop has three components. Most teams have the first, some have the second, almost none have the third.

1. Signal detection: Identifying which tickets point to documentation gaps. Pylon surfaces conversation patterns across Slack channels. Intercom and Plain offer similar tagging and clustering. The tooling exists.

2. Prioritization: Not every ticket is a docs gap. Some are bugs, some are feature requests, some are edge cases affecting one customer. Filter for: which questions repeat, which affect onboarding, which block self-serve adoption?

3. Action: This is where it breaks down. Someone needs to take the support answer, restructure it for a public audience, verify it against the current product state, and ship it as a documentation update. That "someone" is usually nobody.

Here is a triage template to connect signal to action:

# support-to-docs triage template
name: Documentation gap triage
trigger: support_ticket_tagged_docs_gap
steps:
  - classify:
      type: [missing_page, incomplete_steps, outdated_content, wrong_example]
      affected_page: "URL or path of the doc that needs updating"
      frequency: "How many times this question appeared in last 30 days"
  - prioritize:
      score: frequency * customer_tier_weight
      threshold: 3  # Act on anything asked 3+ times
  - action:
      if_missing_page: "Create new doc from support answer template"
      if_incomplete: "Add missing steps from ticket resolution"
      if_outdated: "Flag for engineering review and update"
      if_wrong_example: "Replace with verified working example"

A Real Example: P0 Security

P0 Security had 13+ cloud integrations, each requiring step-by-step guides for configuring just-in-time access controls. Their documentation was sparse: 76 commits across 28 months, averaging 2.7 commits per month. When docs were incomplete, customers filed tickets, and engineers lost 3 to 4 hours per guide writing documentation from scratch.

They did not solve this by hiring a technical writer. They inserted a documentation layer into the existing PR workflow. Documentation PRs were created alongside feature PRs. Engineers went from writing docs (3 to 4 hours each) to reviewing docs (15 minutes each).

The results:

Metric	Before	After
Docs commits per month	2.7	42 merged PRs in the engagement
Engineer time per guide	3-4 hours writing	15 min reviewing
Authoring hours	110 hours	10 hours of review
Time to merge (docs PRs)	Weeks	Under 1 day (median)

Six engineers rotated through reviews, contributing an average of 5 comments per reviewed PR, with some reaching 14 to 16 comments of substantive technical feedback. P0 Security's CTO, Greg Vishnepolsky, put it plainly: "On customer calls now, we can just say, 'look at our docs.' That's new for us."

Why This Matters for Answer Engines

There is a third reason to care beyond cost and onboarding speed. AI referral traffic to websites grew 527% year-over-year through mid-2025. The content that gets cited by AI answer engines is specific, structured, and fresh.

Documentation that answers the exact question a customer asked in a support ticket is precisely the content these engines prefer to surface. Your support tickets are literally telling you what to publish for maximum AI visibility.

Start This Week

Export your top 20 support tickets from last month
Group them by documentation page
If 3+ tickets point to the same gap, that is your first update
Take the support team's best answer for each cluster
Restructure it: direct answer first, steps below, context at the bottom
Publish it as a documentation update, not a blog post
Tag future tickets that could have been self-serve, measure monthly

The data is already in your ticketing system. The answers are already written. The only missing piece is the workflow that turns one into the other.

What does your support-to-docs feedback loop look like? Does your team have a process for turning repeated support tickets into documentation updates, or does the knowledge stay locked in your ticketing system? I would love to hear what has worked (or not worked) for your team.

Originally published at ekline.io.

Why Your Fintech API Code Examples Are a Liability

EkLine.io — 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)

EkLine.io — 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

EkLine.io — 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

EkLine.io — 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

EkLine.io — 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.