DEV Community: Tech code

Agentic IaC Explained: How AI Closes the Terraform Drift Gap

Tech code — Fri, 25 Sep 2026 10:58:25 +0000

TL;DR

A tool that writes Terraform when prompted and stops isn't agentic, the test is whether it keeps comparing declared code against live cloud state on its own schedule, without a human re-triggering the check. Four gaps persist after Day 1 even with full Terraform adoption: drift from console edits, resources that never enter state, unnoticed cost overruns, and configurations that pass terraform plan while still violating policy. Every genuinely agentic system runs the same six-step loop, Observe, Detect, Plan, Validate, Apply, Confirm, and the loop itself is what catches a drifted resource at 3 am before it becomes Monday's incident.

Getting Started: What Agentic Means for Infrastructure

"Agentic" has become one of those words that show up in every product announcement this year, agentic AI, agentic workflows, agentic platforms, often applied to anything with a chat interface bolted on. Most of that is marketing gloss on top of ordinary automation. But underneath the noise, something real has changed in how infrastructure gets managed: AI systems that don't just answer a prompt and stop, but keep watching a live environment and acting on it.

Infrastructure as code is one of the clearest places to see the difference, because the stakes are concrete. A misconfigured chatbot is embarrassing, a misconfigured production database is an incident. Agentic IaC is infrastructure management in which an AI system continuously compares live cloud state against declared infrastructure code, detects gaps, and closes them without requiring an engineer to first notice the problem and manually trigger a fix. The word "continuously" is doing the real work in that definition.

Picture a security group manually opened at 11 pm during an on-call incident and never closed. A reactive tool never sees it happen. An agentic system flags it as drift within its next scan cycle, opens a remediation plan, and either applies it automatically or routes it for approval, hours before anyone notices. A tool that generates a Terraform resource when prompted is helpful, but it isn't agentic, because it has no ongoing relationship with the environment once it returns an answer.

Reactive AI tools, plain Claude, ChatGPT, and GitHub Copilot, used on their own, work the same way regardless of the task: a prompt goes in, an answer comes out, and the tool stops until the next prompt. Ask one what's actually running in a given AWS account right now, and it can't answer, because it has no live connection to that cloud. An agentic system flips that relationship. A platform engineer doesn't ask "is anything drifted right now" every morning, the system has already been checking overnight and surfaces a ranked list of what changed, what it's costing, and what's waiting on approval.

Why Standard IaC Stops Working After Day One

Terraform and tools like it solved a real problem: instead of clicking through a cloud console to build infrastructure by hand, teams could define resources declaratively, store the definitions in Git, and review changes through pull requests. That's what most people mean by IaC adoption, and it's genuinely valuable at the moment infrastructure is first created.

The problem shows up afterward. Take a Kubernetes cluster provisioned entirely through Terraform on day one, every node group, every IAM role, every security group defined in code and reviewed through a pull request. Six months later, an SRE bumps the node pool's instance type directly through the AWS console to handle a traffic spike, because waiting for a PR review during an active incident isn't an option. The change works, the incident closes, and nobody circles back to update the Terraform. From that point forward, every Terraform plan either silently reverts the fix on the next apply or gets excluded from state entirely, and the security group the SRE also opened for debugging that same night never makes it back into code either.

Infrastructure keeps changing after that first deployment, through console edits, CLI commands, and CI/CD pipelines other than the one Terraform runs through, while the Terraform code itself stays exactly as written unless someone actively maintains it. Four gaps grow in that space between the code and the cloud:

Drift: a manual change (a security group port opened for debugging, a tag edited by hand) diverges from what the code declares, and nothing reconciles it automatically
Unmanaged resources: anything created before IaC adoption, or outside an approved workflow, never enters state, so drift detection and policy checks never apply to it
Cost overruns: an oversized instance or an overprovisioned node pool reaches production because nothing evaluates cost impact during the actual deployment, only after the invoice arrives
Policy violations: a configuration can pass terraform plan cleanly while still violating a security or compliance requirement, since plan syntax checks and policy validation are two different things

These four gaps compound because they're invisible on their own. A single drifted security group looks like a minor annoyance. A cloud account with hundreds of drifted resources, a chunk of unmanaged infrastructure, and a handful of policy violations that never got caught looks like a real incident waiting for a trigger.

What Happens Without a Continuous Loop: A Worked Example

Consider a mid-sized platform team running a checkout service on AWS. A customer reports intermittent timeouts, and an engineer picks up the ticket. The obvious first move is to check the load balancer and the service's security group rules, since that's usually where a connectivity issue like this traces back to.

The engineer finds the security group attached to the checkout service references a second security group that isn't present anywhere in the Terraform state file. It was created eighteen months ago during a hotfix, along with a handful of dependent resources, a network interface, an IAM role, and an EBS volume, none of which ever made it into code. To safely change anything here without making the drift worse, those resources need to be codified first, tracing each resource ID across console tabs, writing the corresponding Terraform blocks, and running imports until the plan shows zero diff.

Once the misconfigured rule was identified, the actual fix took about fifteen minutes. Finding it took most of an afternoon, not because the problem was hard, but because nobody had visibility into what was and wasn't under management until the incident forced someone to look. An agentic loop running continuously in the background would have flagged those resources as unmanaged the moment they were created, long before a customer noticed anything.

The Agentic IaC Loop: Six Steps From Observe to Confirm

Every agentic IaC system, whether it's a coding agent wired into live cloud data or a dedicated platform running in the background, executes some version of the same cycle. Tool names vary slightly, but the shape doesn't change.

Observe: read live cloud state directly from provider APIs, not a cached snapshot from the last Terraform refresh
Detect: compare live state against declared IaC state to surface drift, unmanaged resources, and policy gaps
Plan: generate the specific code change that closes the gap, including any dependent resources required to maintain consistency
Validate: run the generated change through policy and guardrail checks before anything gets applied
Apply: execute the change, either automatically for low-risk cases or after a human approves it for higher-risk ones
Confirm: verify the applied change produced the expected result, log what happened, and start the cycle again

The loop running continuously is what separates this from a script. A script executes when triggered and stops, if nobody triggers it, whatever it was supposed to catch sits unnoticed. A drifted resource that shows up at three in the morning stays drifted until someone happens to look, unless something is watching on its own schedule. That gap between something changing and someone noticing is exactly what the loop is built to close.

Two Different Paths to Agentic IaC

Agentic IaC isn't one product category with a single implementation. It shows up in two distinct forms, and knowing which one a tool offers is worth checking before you evaluate it.

The first path is an AI coding agent with live cloud context. Tools like Claude, Cursor, and GitHub Copilot are reactive by default, working against the files open in an editor with no independent view of what's actually running in a cloud account. Connecting a live-data source through an MCP server changes that: the same coding agent can answer questions like "which resources are drifted in production" using real inventory data instead of guessing from a stale config file. The engineer still starts every query, but the answers reflect the actual environment.

The second path is a platform running the full loop on its own, a system with no human in the initiation seat at all, continuously scanning, detecting, planning, validating, applying within approval limits, and confirming, around the clock. This is what catches the drift that happens at three in the morning before it becomes Monday's incident.

These two paths aren't competing. A platform team can use a coding agent for hands-on investigation and codification work, while the same underlying platform runs its autonomous loop in the background for everything nobody's actively watching. Both surfaces drawing from the same data is what makes that combination work, rather than creating two disconnected sources of truth.

The Five Capabilities Every Agentic System Needs

Agentic systems, whether in infrastructure or elsewhere, tend to share the same five underlying capabilities, worth naming to evaluate whether a given tool is genuinely agentic or just has a chat window attached to a script.

Perception: continuous scanning of the live state, not an on-demand refresh triggered by a user
Planning: comparing live state against the declared goal to figure out what's wrong and what fixes it
Reasoning: weighing a proposed change against cost, security, and blast-radius constraints before acting automatically or asking a human first
Tool calling: actually executing the action, running a plan, applying, opening a pull request, triggering a pipeline
Memory: a persistent record of what was observed, decided, and done, so the next decision has context

A tool missing memory re-flags the same drifted tag every week instead of recognizing it's the same resource a specific team keeps hand-editing. A tool missing reasoning can generate a technically valid Terraform change that also deletes a production RDS instance, because nothing weighed the blast radius before applying it. A rule blocking any workflow from resizing or deleting a resource tagged env:production without approval is what reasoning looks like in practice. All five need to be present for the loop to run safely, not just quickly.

How StackGuardian Implements the Agentic Loop

StackGuardian maps its own platform directly onto the five capabilities above, rather than treating AI features as a separate add-on layered over existing tools. Perception runs through SGCode's Cloud Inventory, continuously scanning AWS, Azure, and GCP accounts for every resource, managed or not. Planning runs through SGCode's AI-powered codification, cross-referencing discovered resources against connected state backends to generate the specific Terraform or OpenTofu needed to close the gap. Reasoning runs through Policy Sets built on Tirith or OPA, evaluating every planned change against cost, security, and compliance rules before it can proceed. Tool calling runs through SGOrchestrator Workflows, executing the plan, applying changes, opening pull requests, and triggering webhooks on success, failure, or drift detection. Memory runs through Audit Logs, capturing every policy evaluation and platform action, exportable to JSON or CSV.

The tool-calling step has more going on underneath it than just the workflow running. Every Workflow specifies a Runtime Container, a Docker image that pins the exact Terraform or OpenTofu version, CLI tools, and init scripts used for execution. That's worth taking seriously specifically for agentic remediation: a fix generated for a Terraform 1.5 codebase needs to run against Terraform 1.5, not whatever version happens to be on a shared runner, or the applied change and the declared code will silently diverge again.

Take the checkout service example from earlier and run it through StackGuardian's actual mechanics. Every workflow has an Automated Drift Check toggle configured to run on a schedule rather than waiting for someone to manually trigger a plan. When that hotfix-era security group was created eighteen months ago, a scheduled drift check against the connected AWS account would have surfaced it the same week, not eighteen months later during an incident. Drift runs are queued at lower priority than user-initiated runs, so they don't compete with active deployments for execution capacity, but they still run continuously in the background regardless of whether anyone is watching.

Cost sits inside the same loop, not as an afterthought. Take a developer self-provisioning a database through StackGuardian's Dev Portal for a new feature branch, nobody's watching that request, and it's easy to pick an oversized instance type out of habit or uncertainty about what the workload actually needs. A Policy Set that evaluates that plan against InfraCost data catches it before the workflow applies, either blocking the request outright or flagging it for approval, rather than the oversized instance quietly running for a month until someone notices the bill. That same signal rolls up into Discover dashboards, with separate Compliance, Cost, and Security views that continuously evaluate the connected cloud estate, so a platform team isn't just catching one oversized instance at plan time, they can see cost drift across every workflow in the organization from a single view instead of checking each one individually.

The practical effect is that a question like "which resources should get codified first" doesn't require opening three separate dashboards and manually correlating the results. SGCode's Cloud Inventory identifies what's unmanaged, the IaC Adoption Matrix tracks coverage as a measurable percentage across the estate, and Policy Sets flag what's already violating a compliance rule, giving the platform team a single ranked view instead of three disconnected lists.

That same underlying data is available outside the platform too, through StackGuardian's hosted MCP server, added in v1.31.4. It connects tools like Claude and ChatGPT directly to StackGuardian's read-only APIs, so a query like "why did workflow run #1247 fail" or "what's the current status of all stacks in my organization" run from inside an AI assistant pulls from the same drift, compliance, and execution data the platform itself uses. The same server handles more targeted questions too, "which workflows are still using template revision 2" surfaces exactly which deployments need updating before a rollout, and "assess the health of every workflow in this group before we ship" aggregates status across a whole Workflow Group instead of checking each one by hand. No dashboard-hopping required to get an answer either way.

The Governance Layer an Agentic System Needs Before Production

None of the automation above is safe to run unsupervised without a governance layer sitting in front of it. An AI agent with unrestricted Terraform access can run terraform destroy against production resources just as easily as it can fix a drifted tag, faster than any human could intervene. The capability to act autonomously and the judgment to know when not to are two separate things, and only one comes for free with a capable model.

StackGuardian's Policy Sets sit exactly at this boundary, evaluating every planned change through Tirith or OPA before anything applies. Each policy rule has two configurable outcomes, an action when the policy passes and an action when it errors, with five possible statuses: Pass, Fail, Warn, Approval Required, or Unevaluated. A violation can block the deployment outright, log a warning and proceed, or route to a named approver, rather than defaulting to either full autonomy or full manual review for every change. Policies scope at three levels, organization-wide, Workflow Group, or Connector, the practical version of a blast-radius limit: a policy governing a sandbox Workflow Group doesn't need, and shouldn't have, the same restrictions as one governing production.

Every action, whether it ran automatically or waited for approval, is logged in Audit Logs, including what changed, who evaluated it, and the outcome, exportable to JSON or CSV. That audit trail is what turns "the platform did something" into an answerable question after the fact, instead of a black box nobody can reconstruct.

Why Trust Remains the Real Blocker

The technology to run an agentic loop exists today, the harder problem is convincing teams to let it act without a human double-checking every step. This isn't irrational, it's the same reason approval gates for production Terraform apply in the first place. An engineer who wouldn't approve their own unreviewed pull request to production shouldn't be expected to trust an unreviewed AI-generated one either.

Terraform, OpenTofu, and similar tools remain the execution layer regardless of how much of the surrounding work becomes agentic. What changes is the manual work that used to happen around terraform apply, tracing dependencies, noticing drift, writing the fix, checking it against policy, all of which historically fell on an engineer to catch by hand. The trust gap closes as guardrails, approval gates, and audit trails mature, not as agents get better at generating code in isolation.

Where Should You Start With Agentic IaC

Agentic IaC isn't a single feature to turn on. It's a combination of continuous visibility into what's actually running, a policy layer that evaluates changes before they apply, and an audit trail that makes every autonomous action reviewable after the fact. Teams evaluating this space should look for all three together rather than a chat interface bolted onto an existing IaC tool, since a system that can generate a fix but can't see live state, or can see live state but has no guardrails, isn't actually running the loop.

The fastest way to know where an environment stands is to check how much of it is genuinely unmanaged today, rather than assume. StackGuardian's Cloud Inventory runs that check directly against a connected AWS, Azure, or GCP account, and the IaC Adoption Matrix turns the result into a measurable coverage percentage rather than a guess. For teams wanting to see how the six-step loop maps onto their own environment, that inventory scan is the concrete first step, not a chat interface to experiment with in the abstract.

Frequently Asked Questions

What is agentic IaC?

Agentic IaC is infrastructure management in which an AI system continuously compares the live cloud state against declared infrastructure code, detects drift or policy gaps, and generates and applies fixes within defined guardrails, without requiring a human to notice the problem and manually trigger a fix.

What does agentic mean in AI?

An agentic AI system pursues a goal continuously rather than responding to a single prompt and stopping. It observes an environment, decides what needs to change, takes action, checks the result, and repeats the cycle on its own, compared to a standard tool that waits for input and produces output once.

Will AI agents replace Terraform?

No. Terraform, OpenTofu, and similar tools remain the execution layer through which agentic systems generate and apply changes. What AI changes is the manual investigation and remediation work that used to sit between the code and the live cloud, not the underlying IaC engine itself.

How does StackGuardian implement agentic IaC?

StackGuardian runs the observe-detect-plan-validate-apply-confirm loop across its own platform: SGCode's Cloud Inventory for continuous discovery, AI-powered codification for planning, Policy Sets (Tirith or OPA) for validation, SGOrchestrator Workflows for execution, and Audit Logs for the record of what happened. The same live data is exposed to external tools such as Claude and ChatGPT through StackGuardian's hosted MCP server.

Does StackGuardian's MCP integration work with Claude and ChatGPT?

Yes. StackGuardian's hosted MCP server, added in v1.31.4, connects AI tools directly to StackGuardian's read-only APIs, so a query like "show me drifted resources in production" or "which workflows are using an outdated template revision" returns real data from a connected organization instead of a guess based on local files.

What stops an AI agent from making a destructive change by mistake?

Policy Sets evaluate every planned change against cost, security, and compliance rules before it applies, and policies scoped to a Workflow Group or Connector can restrict which resources an agent-driven workflow can touch. Combined with Approval Required gates for higher-risk changes and a full audit trail of every action in Audit Logs, this is what keeps autonomy bounded rather than open-ended.

What Is Brownfield Infrastructure? A Guide to Codifying What Already Exists

Tech code — Thu, 24 Sep 2026 12:37:56 +0000

TL;DR

Brownfield infrastructure is any cloud resource running in production with no corresponding Infrastructure as Code, created through a console click, a CLI command, or a script nobody checked into version control. It accumulates for ordinary reasons, most often an incident hotfix that never gets backfilled into code, and it sits outside drift detection, policy enforcement, and audit logging until someone goes looking for it. This guide covers why it happens, what it actually costs to leave alone, and how discovery and codification bring it back under management.

Every cloud environment beyond a certain age has some brownfield infrastructure. This isn't a sign that a team did something wrong. It's the normal byproduct of how infrastructure actually gets built under deadline pressure, incident response, and years of accumulated changes that outlast whoever made them.

Take a payments team at a mid-sized fintech company running its checkout service on AWS. A traffic spike during a product launch triggers timeouts. An on-call engineer traces it to the API Gateway, which needs a new integration route pointing checkout traffic to a backup Lambda, and wires it up directly through the AWS CLI at 11 pm, because waiting for a PR review during an active incident isn't realistic. The fix works. The incident closes. Nobody circles back to add that integration to the Terraform module managing every other route. Eighteen months later, that manually created integration is still sitting there, undocumented, unreviewed, and invisible to every tool supposedly watching the account.

This guide follows that same resource through its whole lifecycle, why it happened, what it costs to leave alone, and what it takes to bring it back under management.

Getting Started: Understanding Brownfield Infrastructure

Brownfield infrastructure is any cloud resource that exists and runs in production without a corresponding code definition. The API Gateway integration from the checkout incident is a clean example: it works, it's actively routing traffic, and it has no .tf file, no state entry, and no mechanism for any platform to know it exists.

Greenfield infrastructure is the opposite case. Resources get defined in code from the moment they're created, reviewed through a pull request, and tracked in state from day one. Most teams start there. Few stay there, and the gap shows up across four dimensions. Origin is the first split: brownfield resources come from a console click, a CLI command, or an ad hoc script, while greenfield resources come from Terraform, OpenTofu, or another IaC tool from the start. Visibility follows directly from that: brownfield resources are invisible to state and drift checks, while greenfield resources are tracked from creation. Review works the same way: brownfield resources are created outside any pull request process, while greenfield resources are reviewed before they exist. And governance depends on all three: brownfield resources carry no policy coverage until someone codifies them, while greenfield resources are policy-checked before every apply.

Both categories coexist in the same account, often in the same VPC. The payments team's networking layer is fully codified. The integration sitting next to it isn't.

Why Does Brownfield Infrastructure Keep Accumulating?

The checkout service incident isn't a one-off. It's the most common pattern behind brownfield accumulation: an engineer makes the right call under pressure, and the code never catches up. The same pattern shows up in a few recurring forms:

Incident hotfixes: the checkout example above, where a manual integration resolves the outage but the module update meant to follow it never happens
PR review bottlenecks: a fix that could go through code review takes 48 hours to approve, so someone ships it manually and means to backfill later
Pre-adoption legacy resources: infrastructure provisioned before a team adopted Terraform at all, left untouched because nobody wants to risk breaking something that currently works
Shadow IT: a team spins up resources outside the platform team's approved workflow, often without realizing there was a workflow to follow
Mergers and acquisitions: an acquired company's AWS account arrives with years of infrastructure history and zero documentation

Each of these is individually reasonable. The problem is cumulative, not any single decision.

What Risk Does Unmanaged Infrastructure Create?

Eighteen months after the checkout incident, nothing has changed about that integration except that nobody remembers which backend it was supposed to be temporary. It carries risk precisely because nothing is watching it, and that risk compounds across four categories:

No drift detection: the target Lambda or timeout could be changed further tomorrow and nothing would flag it, since there's no baseline to compare against
No policy enforcement: a policy requiring every integration to use a validated timeout and payload format never evaluates this route, because it was never part of a governed workflow
No audit trail: there's no record of who created the integration, when, or why, which becomes a real problem the moment a security review asks
Cost blind spots: if the same incident had also spun up an oversized instance, nothing would catch it until the invoice arrived

A single forgotten integration looks like a minor gap. An account with hundreds of unmanaged resources like it, alongside stale IAM roles nobody remembers granting, looks like an incident that hasn't happened yet.

How Do You Find Out How Much Brownfield Infrastructure Exists?

The payments team doesn't know that integration exists until someone runs a discovery scan against the account. Guessing based on memory consistently underestimates the real number, since the resources that come to mind are the recent ones, not the ones sitting quietly from eighteen months ago.

Measuring starts with a cloud inventory scan cross-referenced against connected state backends. The scan discovers every resource actually running in the account, and the cross-reference against state determines which resources have a corresponding .tf definition and which don't. For the payments team, that scan surfaces the exact API Gateway integration from the incident, along with whatever else has accumulated since.

How Do You Turn Brownfield Infrastructure Into Managed Code?

Codification generates the missing IaC for an existing resource without destroying and recreating it. For the payments team's integration, the route keeps sending checkout traffic to the backup Lambda throughout the process. What changes is whether a platform can see and govern it afterward. The technical sequence runs in five steps: discover the live integration against connected state backends to confirm it has no existing .tf definition, generate Terraform configuration inferred from the resource's live setup, resolve its dependencies on the parent API and target Lambda, validate the output through an internal terraform plan confirming zero diff, and publish the result as a pull request against the team's existing repository.

The payments team already manages its API Gateway through a reusable module, so generated code slots a new entry into the existing for_each map rather than writing a standalone resource block:

module "apigatewayv2_integration" {
  source   = "./modules/apigatewayv2_integration"
  for_each = var.apigatewayv2_integrations

  api_id                 = module.apigatewayv2_api[each.value.api_key].id
  integration_type       = each.value.integration_type
  integration_method     = each.value.integration_method
  integration_uri        = each.value.integration_uri
  payload_format_version = each.value.payload_format_version
  timeout_milliseconds   = each.value.timeout_milliseconds
  connection_type        = each.value.connection_type
}

Running a plan after adding the missing entry confirms the generated configuration actually matches what's live:

$ terraform plan

module.apigatewayv2_integration["checkout_backup"]: Refreshing state...

No changes. Your infrastructure matches the configuration.

A zero-diff plan is what makes the pull request safe to merge. Skipping this validation step is the most common mistake teams make when codifying manually. Generated code that looks correct but doesn't quite match the live resource's actual configuration produces an unexpected diff the first time anyone runs a plan against it, often more disruptive than leaving the resource unmanaged in the first place.

Not every unmanaged resource carries the same urgency once a scan surfaces fifty of them. Production resources come before sandbox ones; security-sensitive resources like IAM roles and security groups come before cosmetic tagging fixes; resources with many dependents come before standalone leaf resources; and recently changed resources come before stable ones that haven't been touched in years. Tracking IaC coverage as a measurable percentage, rather than a one-time audit, turns this into an ongoing target instead of a project that stalls after the first sprint.

How Does StackGuardian Handle Brownfield Codification?

SGCode was built specifically for this problem. It connects to AWS, Azure, and GCP accounts through its Cloud Inventory, discovers every resource across the environment, and classifies coverage against connected state backends, whether the gap is three days old or three years old, like the checkout API Gateway integration.

Discovered infrastructure gets organized into Infra Projects, a structured way to group related resources rather than working through a flat, undifferentiated list. From there, selecting the integration for codification triggers AI-powered generation: SGCode produces Terraform configuration that matches the payments team's existing module pattern, resolves API and Lambda target dependencies, and validates the output through an internal plan run before proposing anything.

The generated code publishes directly as a pull request to the payments team's connected repository. Once that PR merges, workflows created from SGCode automatically update to point to the target branch, so there's no manual reconfiguration step to remember afterward. State Backends management handles where the newly codified resource's state actually lives, connecting to the team's existing backend rather than requiring a separate setup process.

Once codified, the integration becomes eligible for governance through SGOrchestrator. A Tirith policy scoped to the payments team's Workflow Group can now evaluate it directly, something that was impossible while the resource sat outside state:

{
  "meta": {
    "required_provider": "stackguardian/terraform_plan",
    "version": "v1"
  },
  "evaluators": [
    {
      "id": "require-integration-timeout",
      "description": "Require an explicit timeout on every API Gateway integration",
      "provider_args": {
        "operation_type": "attribute",
        "terraform_resource_type": "aws_apigatewayv2_integration",
        "terraform_resource_attribute": "timeout_milliseconds"
      },
      "condition": {
        "type": "IsNotEmpty",
        "error_tolerance": 1
      }
    }
  ],
  "eval_expression": "require-integration-timeout"
}

That policy now runs against the checkout integration on every future change, something Sentinel-style, plan-time enforcement could never do while the resource had no state entry to evaluate.

What Changes Once Brownfield Infrastructure Is Codified?

For the payments team, the shift is concrete. The checkout integration goes from a resource nobody was watching to one covered by every governance mechanism at once: Automated Drift Check now runs on a schedule against it where none existed before, Tirith or OPA evaluates every planned change before it applies where no policy coverage existed before, every action gets logged in Audit Logs and is exportable to JSON or CSV where no audit trail existed before, and Policy Sets can evaluate the resource against InfraCost data where its cost impact was previously unknown.

None of this required touching the resource itself. The integration kept routing checkout traffic to the backup Lambda exactly as it did before. What changed is whether anything is watching it, checking it, and recording what happens to it going forward.

Getting Brownfield Infrastructure Under Control

Brownfield infrastructure isn't solved by a one-time audit. The payments team can codify every resource currently sitting unmanaged and still have a new batch within a year, produced by the same operational pressure that created the checkout integration in the first place. What actually works is treating IaC coverage as a metric to track continuously, the same way uptime or error rate gets tracked, rather than a project with a defined end date.

The starting point is the same, no matter how large the gap is. Run a discovery scan, see the real number, and prioritize from there using production impact, security sensitivity, and dependency count as the ranking criteria. Explore StackGuardian's SGCode to see how discovery and codification work against a live cloud account, or read how the same platform handles ongoing policy enforcement once resources are brought under management.

FAQs

1. What's the difference between brownfield and greenfield infrastructure?

Greenfield infrastructure is defined in code from the moment it's created, reviewed through a pull request, and tracked in state from day one. Brownfield infrastructure exists and runs in production without any of that, created through a console click, a CLI command, or a script that was never checked into version control.

2. How do you find unmanaged cloud resources?

Run a cloud inventory scan against the live account and cross-reference the results against connected Terraform or OpenTofu state backends. Resources that show up in the live scan but have no corresponding state entry are unmanaged. Tools like SGCode automate this cross-reference directly.

3. Can you generate Terraform automatically from existing infrastructure?

Yes. AI-powered codification tools generate Terraform or OpenTofu configuration for a discovered resource, resolve its dependencies on other resources, and validate the output through an internal plan run before publishing it as a pull request, rather than requiring someone to write the resource block by hand.

4. What's the risk of leaving infrastructure uncodified?

Uncodified resources sit outside drift detection, policy enforcement, and audit logging. Changes go unnoticed indefinitely, security and compliance checks never evaluate the resource, and there's no record of who created it or why, which becomes a real problem the moment a security review or an incident forces someone to explain it.

5. Does codifying brownfield infrastructure require downtime?

No. Codification generates the missing IaC definition and imports the resource into state; it doesn't destroy or recreate anything. The resource keeps running exactly as before, and validating the generated configuration through an internal plan run confirms the code matches the resource without changing the live infrastructure.

6. How much brownfield infrastructure does the average cloud account actually have?

There's no universal figure, since it depends heavily on how long an account has existed and how consistently a team enforced IaC-only provisioning. What's consistent across teams that run a discovery scan for the first time is that the real number tends to be significantly higher than what anyone estimated from memory beforehand.

7. Is brownfield infrastructure the same thing as infrastructure drift?

No, though they're related. Drift describes a resource already tracked in code that diverges from its declared configuration. Brownfield infrastructure describes a resource that was never tracked in code, so it has no declared configuration to drift from in the first place.

Policy as Code Tools Using OPA and Rego for Infrastructure Governance

Tech code — Thu, 27 Aug 2026 10:24:35 +0000

TLDR

Open Policy Agent and its Rego language have become the default foundation for policy-as-code across Kubernetes, Terraform, and CI/CD pipelines. But "OPA tooling" now spans a fragmented set of products, some built on top of it, some evaluating the same Rego rules differently, and one major commercial layer currently being wound down. This post covers the real tools worth knowing in 2026, including a governance update every team evaluating OPA needs to see first.

Policy as code has become table stakes for infrastructure governance. Almost every team running Terraform, Kubernetes, or a multi-cloud environment at any real scale has some version of "policies that block bad deployments before they ship" running somewhere in the pipeline. What's less settled is which tool actually runs those policies, since "OPA" and "Rego" are used as umbrella terms for a genuinely fragmented ecosystem beneath the surface.

This post covers the tools that actually matter in 2026: what each one does, where it fits, and one governance change that affects how confidently teams should evaluate the commercial layer around OPA right now.

What Does the Styra-Apple Deal Mean for OPA in 2026?

Open Policy Agent went through a real transition in August 2025. Apple hired OPA's three original creators, along with several senior engineers from Styra, the company that built and commercialized OPA, without acquiring Styra itself. Styra's commercial products, Styra DAS and Enterprise OPA, are being sunset, with their code folded into the community-maintained OPA project.

OPA itself isn't going anywhere. It remains a CNCF-graduated project, with governance and licensing unchanged, the same maintainer list aside from employer changes for those who joined Apple, and the same monthly release cadence, as confirmed directly by the project itself. Production use remains broad at Netflix, Google Cloud, Goldman Sachs, T-Mobile, and hundreds of other organizations, and that adoption hasn't shifted since the Apple-Styra transition, since none of it depended on Styra's commercial layer to begin with.

The practical takeaway: trust OPA and Rego as a foundation; they're stable and independently governed, but don't evaluate Styra's commercial products as an ongoing option. Any tool built on raw OPA rather than Styra's sunset layer isn't affected by this at all.

1. StackGuardian

StackGuardian runs two policy engines side by side rather than forcing a single choice.

Key features:

Tirith: StackGuardian's own JSON-based framework; three-part structure (meta, evaluators, eval_expression) combining checks with &&, ||, ! logic
Native OPA support: source Rego policies directly from a Git repo, with an OPA Deciding Query pointing at the rule that returns the final decision
Three scope levels: organization-wide, specific Workflow Groups, or individual Connectors tied to a cloud account
Five rule statuses: Pass, Fail, Warn, Approval Required, Unevaluated, each independently configurable per policy
NoCode Policy Builder: generates the same Tirith output through a UI for teams that don't want to write JSON or Rego

Pros:

Covers both Terraform plans and cross-system policies (Kubernetes, API gateways) under one platform
No forced choice between writing Rego and using a simpler format
Every evaluation logs automatically, with no separate audit tool required
Scope model prevents a sandbox policy from accidentally governing production

Pricing: Workflow-based, not tied to resource count under management. Current tiers and details at stackguardian.io/pricing.

2. Open Policy Agent (OPA)

OPA is the foundation on which the rest of this list builds: a general-purpose, CNCF-graduated policy engine that decouples decision-making from enforcement.

Key features:

Queried over HTTP or embedded directly into an application
Evaluates Rego, a declarative language purpose-built for hierarchical, structured data
Runs identically across Kubernetes, Terraform, API gateways, and CI/CD
A policy written once in Rego can run unchanged wherever OPA is deployed

Pros:

Vendor-neutral, no single company controls the roadmap
Massive existing ecosystem of policy libraries and integrations
One policy language across every system that queries it

Cons:

Real Rego learning curve for teams coming from YAML or general scripting
No built-in scope management, approval routing, or audit trail; all of that gets built separately

Pricing: Free and open source, self-hosted. No commercial tier since Styra's enterprise offerings are sunsetting.

3. Conftest

Conftest is a small, open-source CLI from the OPA project itself, built for teams that want OPA's policy model without having to stand up a server.

Key features:

Evaluates Rego policies against structured config files directly
Accepts Terraform plan JSON, Helm charts, Kustomize output, Kubernetes manifests, and Dockerfiles as input
Same Rego rules used for OPA proper run unchanged in Conftest
Ships as a single binary, drops into CI with a few lines of YAML

Pros:

No server to run or maintain
Fast to add as a pass/fail gate on a pull request
Policy logic written once can graduate to full OPA later without a rewrite

Cons:

No scope management, drift detection, or approval workflow on its own
Best paired with something else for teams that need those pieces

Pricing: Free and open source.

4. OPA Gatekeeper

Gatekeeper is a Kubernetes-native policy controller built directly on OPA, optimized for one job: admission control inside a cluster.

Key features:

Constraints defined as Kubernetes Custom Resource Definitions
Rego policies underneath, evaluated at admission time
Rejects non-compliant workloads before creation, not after
Common uses: restricting container images, enforcing naming conventions, requiring specific labels or annotations

Pros:

Purpose-built for Kubernetes, tightly integrated with the cluster API
Blocks violations before they exist rather than flagging them later
Backed by the CNCF community, not a single vendor

Cons:

Doesn't extend to Terraform plans or cloud-provider configuration outside the cluster
Teams managing infrastructure beyond Kubernetes typically need to pair it with a broader tool

Pricing: Free and open source.

5. HCP Terraform's OPA Policy Sets

HashiCorp's own platform supports OPA as an alternative to Sentinel, its proprietary policy language, through Run Tasks.

Key features:

Teams already on HCP Terraform can write Rego instead of Sentinel
Same plan-time enforcement point as native Sentinel policies
Runs inside HCP Terraform's existing Run Task framework

Pros:

No proprietary policy language required for teams that prefer open tooling
Existing Rego policies from elsewhere may port over with minimal changes

Cons:

OPA policies here still only evaluate plans running through HCP Terraform specifically
A team wanting the same Rego policy to also govern Kubernetes or a CI pipeline maintains that enforcement separately

Pricing: Tied to the HCP Terraform tier, not priced separately. As of mid-2026, tiers run Essentials at $0.10 per managed resource/month, Standard at $0.47, and Premium at $0.99, all billed hourly on peak resource count. Audit logs are limited to Standard and Premium; Enterprise (self-managed) is quote-based. A free tier covers up to 500 managed resources.

Should You Still Consider Styra DAS or Enterprise OPA in 2026?

Styra DAS and Enterprise OPA were, for years, the default answer for teams wanting to manage OPA at scale, centralized policy authoring, compliance auditing, and runtime enforcement across a fleet of deployments. That's no longer a forward-looking recommendation.

Following Apple's hiring of Styra's core team in August 2025, both products are being wound down, with their capabilities merging into the community OPA project over an unspecified timeline. Existing customers aren't left with nothing overnight, but there's no ongoing commercial roadmap and no new subscriptions being sold.

Teams starting fresh in 2026 shouldn't plan around this layer. The safer path is to build on OPA directly or to choose a platform that layers management and enforcement on top of the open project, not a sunset commercial one.

Which Policy as Code Tool Should You Actually Use?

The decision usually comes down to how much of the governance surface is Kubernetes-only versus spread across Terraform, cloud accounts, and CI/CD. Gatekeeper fits the former; Conftest, raw OPA, or a broader platform fit the latter.

It also depends on how much Rego expertise the team actually has or wants to build. Raw OPA and Conftest both assume comfort writing and debugging Rego. Teams without that appetite get more from a platform offering a no-code or JSON-based alternative alongside native OPA support, so policy authoring doesn't become a bottleneck concentrated in one or two engineers.

The last factor is whether the team needs a managed platform to handle scope, approval routing, and audit logging, or just a policy evaluation step within an existing pipeline. Conftest and Gatekeeper are both narrow by design, a feature for teams that already have the surrounding infrastructure. Teams that don't have that yet get more out of a platform that provides scope, drift detection, and audit trails, all within the same system that runs the policies.

Where Does This Leave Policy as Code Going Into 2026?

OPA and Rego remain the right foundation for policy-as-code in 2026, regardless of what's happening commercially around Styra. The project itself is stable, CNCF-governed, and unaffected in any technical sense by the transition. What changed is which layer sits on top of it, and teams choosing tools right now should weigh that layer on its own merits rather than assuming the ecosystem around OPA looks the same as it did two years ago.

For teams that want both paths available without committing to one, a JSON-based engine for straightforward IaC and workflow policies, and full OPA support for anything that needs to run across systems, StackGuardian's policy engine runs Tirith and OPA side by side under the same scope model, rule actions, and audit trail.

FAQs

1. Do Sentinel policies in HCP Terraform port to OPA and Rego?

No. Sentinel is a proprietary policy language specific to HashiCorp's platform, and it doesn't translate automatically to Rego. Teams switching from Sentinel to OPA, whether inside HCP Terraform's own OPA-based Run Tasks or on another platform, need to rewrite the underlying policy logic rather than migrate it directly.

2. Can StackGuardian's Tirith and OPA policies enforce the same rule, or do they need to be written twice?

They're separate engines with different syntaxes, JSON for Tirith versus Rego for OPA, so the same rule needs to be authored once in each format if a team wants both available. What doesn't duplicate is the scope model, rule actions, and audit trail, which apply identically to policies from either engine within the same Workflow Group.

3. Is Conftest a replacement for a full policy management platform?

No. Conftest is a lightweight CLI for running Rego checks against structured config files in a CI pipeline, it has no scope management, approval routing, or audit logging built in. Teams needing those capabilities typically pair Conftest with a broader platform or graduate to running OPA as a managed service.

4. Does OPA Gatekeeper work for governing Terraform-provisioned cloud resources?

Not directly. Gatekeeper is Kubernetes-native, enforcing policy at admission time inside a cluster. It has no mechanism for evaluating a Terraform plan or a cloud-provider configuration outside Kubernetes, so teams managing infrastructure beyond a cluster typically need Gatekeeper plus a separate tool for the rest.

5. What happens to existing Styra DAS or Enterprise OPA policies if a team doesn't migrate?

Existing customers aren't cut off immediately, but there's no ongoing commercial roadmap or new subscriptions being sold following the products' sunset. Policies written for Styra DAS specifically will need to move to community-maintained OPA or another management layer over time, since Styra's capabilities are being folded into the open project rather than continuing as a standalone commercial product.

ToFU, MoFU and BoFU stages of the marketing funnel for B2B SaaS

Tech code — Wed, 24 Dec 2025 10:49:29 +0000

TL;DR

Understand the Funnel: ToFU, MoFU, and BoFU stages are essential for mapping the buyer's journey in B2B SaaS marketing.
Targeted Strategies: Each stage requires distinct strategies and content types to effectively engage potential customers.
Content Focus: ToFU focuses on awareness, MoFU on nurturing interest, and BoFU on facilitating conversions.
Real-World Examples: Companies like Salesforce and Shopify illustrate effective funnel strategies through targeted campaigns.
Performance Metrics: Each stage has specific metrics to measure success, guiding adjustments to marketing efforts.

In B2B SaaS marketing, understanding the ToFU, MoFU, and BoFU stages of the marketing funnel is crucial for creating effective strategies that resonate with potential customers. ToFU (Top of Funnel) focuses on generating awareness, MoFU (Middle of Funnel) nurtures interest, and BoFU (Bottom of Funnel) drives conversions. This structured approach allows marketers to tailor their content and strategies according to the buyer's journey, ensuring that each stage effectively addresses the needs and questions of potential customers. By breaking down the marketing process into these three stages, businesses can enhance their engagement and conversion rates, ultimately leading to greater success in the competitive SaaS landscape.

ToFU, MoFU, and BoFU are integral components of the marketing funnel that represent the stages a buyer goes through, from initial awareness to final purchase. The ToFU stage aims to capture attention and generate interest through educational and informative content, while MoFU focuses on nurturing leads by providing more detailed information about solutions. Finally, BoFU is where potential customers are ready to make a purchase decision, requiring targeted strategies that emphasize product differentiation and compelling offers. Understanding these stages allows marketers to create tailored content that aligns with the buyer's journey, improving engagement and conversion rates.

How It Works / Process Breakdown

Input

The input for the marketing funnel consists of various content types tailored to each stage. For ToFU, this includes blogs, videos, and educational resources aimed at raising awareness. MoFU inputs involve more detailed content like whitepapers and case studies that provide solutions. BoFU inputs focus on product-specific information, offers, and testimonials.

Processing

In the ToFU stage, the primary goal is to attract potential customers by addressing their pain points without direct selling. MoFU processes involve nurturing leads through targeted emails and landing pages that provide deeper insights into the product. In the BoFU stage, the focus shifts to converting leads through compelling offers and product demonstrations.

Output

The output at each stage varies significantly. ToFU outputs include increased website traffic and brand awareness. MoFU outputs are measured by lead engagement and information requests, while BoFU outputs focus on conversion metrics such as demo sign-ups and sales closures.

Limitations

Each stage has inherent limitations. ToFU may attract a broad audience but lacks intent. MoFU can nurture leads but may not convert all interested parties. BoFU is limited to a smaller, highly qualified audience, making it crucial to provide compelling reasons for purchase.

Practical Example / Use Case

Consider a hypothetical SaaS company, ACME, that offers developer productivity tools. In the ToFU stage, ACME creates informative blog posts addressing common pain points for developers, such as code testing challenges. This content attracts a wide audience searching for solutions. Moving to the MoFU stage, ACME produces detailed whitepapers that outline how their tools can solve these problems, nurturing the leads generated in ToFU. Finally, in the BoFU stage, ACME offers a free trial of their product, allowing potential customers to experience the benefits firsthand, thereby increasing the likelihood of conversion.

Key Takeaways

Understanding the ToFU, MoFU, and BoFU stages is essential for effective B2B SaaS marketing.
Each stage requires distinct content and strategies tailored to the buyer's journey.
ToFU focuses on awareness, MoFU on nurturing leads, and BoFU on driving conversions.
Real-world examples from companies like Salesforce and Shopify demonstrate successful implementation of these strategies.
Performance metrics specific to each stage guide marketers in optimizing their efforts.

Conclusion

The ToFU, MoFU, and BoFU stages of the marketing funnel are vital for crafting a comprehensive B2B SaaS marketing strategy. By understanding and implementing tailored content and strategies for each stage, businesses can enhance their engagement with potential customers and improve conversion rates. This structured approach not only streamlines the marketing process but also aligns with the buyer's journey, ultimately driving greater success in the competitive SaaS landscape.

About Infrasity

Infrasity helps early-stage B2B SaaS and DevTools startups with developer marketing through hands-on technical content. We work on technical blogs, product documentation, and use-case driven guides built from real product workflows. The focus is on reducing evaluation and onboarding friction for engineers. Everything we create is grounded in how developers actually discover and assess tools.

Bad Documentation Examples: Why Developers Drop Off | Fixes

Tech code — Mon, 15 Dec 2025 20:46:38 +0000

Developers often abandon platforms due to poor documentation. This article explores common pitfalls in B2B SaaS documentation, their impact on user experience, and effective strategies for improvement.

Introduction

Bad documentation is a significant barrier to developer adoption. It can lead to confusion, increased support tickets, and ultimately, user abandonment. Documentation should provide clear, actionable guidance to help users navigate a product effectively. In essence, effective documentation is a structured, user-friendly resource that minimizes the need for external support.

Common Documentation Pitfalls

1. No Actual Documentation or Broken Docs

The absence of documentation is one of the most detrimental issues. Developers rely on integration guides and setup instructions. Without these, they face immediate disruption. For instance, when Infrasity collaborated with a cost optimization platform, the lack of integration documentation led to low user retention and broken onboarding.

2. Outdated Documentation

Outdated information can severely undermine trust. When documentation doesn't align with the current product, users waste time troubleshooting. This often results in increased support tickets. For example, one customer’s documentation was created during early development and quickly became obsolete, leading to confusion and inconsistent onboarding.

3. Overwhelming Volume Without Flow

Excessive information without a clear structure can overwhelm users. When documentation is scattered across multiple pages, developers struggle to find critical information. A centralized, step-by-step flow can significantly enhance user experience and reduce confusion.

4. Writing for Experts Instead of Beginners

Documentation often assumes prior knowledge, which can alienate beginners. This gap leads to slower onboarding and increased errors. For example, an AI-powered Kubernetes optimization platform's documentation failed to provide context for its components, causing friction for new users.

5. Accessibility Issues

If documentation is hard to find, it fails its purpose. Poorly indexed or scattered content can frustrate users and increase support tickets. Centralizing documentation into a structured hub can improve discoverability and streamline onboarding.

6. The One-Trick Pony

Documentation that lists commands without context is ineffective. Developers need to understand why an action is necessary and what problem it solves. Adding context, expected outcomes, and real-world examples can transform static documentation into a valuable resource.

7. Not Following Great Documentation

Learning from effective documentation can save time and prevent errors. Teams should study proven patterns to enhance their documentation practices.

How It Works / Process

Input: Identify existing documentation and gather user feedback to pinpoint common issues.
Processing: Analyze the documentation for gaps, outdated content, and structural flaws. Engage with developers to understand their needs.
Output: Revise the documentation to include clear, actionable steps, context, and examples. Ensure it is accessible and well-organized.
Edge Cases: Consider scenarios where users may have varying levels of expertise. Tailor documentation to accommodate both beginners and advanced users.

Practical Example / Use Case

Consider a cloud cost management platform that initially had no integration documentation. Developers were unable to connect the platform with their existing systems, leading to frustration and abandonment. Infrasity created comprehensive integration docs, including clear steps and use cases. This transformed the onboarding experience, enabling developers to navigate the platform confidently.

Key Takeaways

Bad documentation can significantly hinder developer adoption and increase support tickets.
Centralizing and structuring documentation improves discoverability and user experience.
Writing for beginners ensures that all users can effectively navigate the product.
Providing context and real-world examples enhances the usefulness of documentation.
Learning from successful documentation practices can streamline improvement efforts.

FAQ

What are the signs of bad documentation?

Signs include missing or outdated content, overwhelming information without structure, and a lack of context for commands or features.

How can I improve existing documentation?

Start by gathering user feedback, identifying gaps, and restructuring content for clarity and flow. Include context and examples to enhance usability.

Why is context important in documentation?

Context helps users understand the purpose of commands and how they fit into workflows, reducing confusion and errors.

How often should documentation be updated?

Documentation should be reviewed and updated regularly, especially after significant product changes or user feedback.

Conclusion

Effective documentation is crucial for enhancing user experience and fostering developer adoption. By addressing common pitfalls and implementing best practices, organizations can create valuable resources that empower users and streamline onboarding processes.

Bad Documentation Examples: Why Developers Drop Off | Fixes

Tech code — Mon, 15 Dec 2025 20:36:12 +0000

Learn How Poor Documentation Affects Developer Adoption

In this article, you'll discover the most common pitfalls in product documentation that hinder developer engagement and adoption. You'll also learn effective strategies to enhance documentation quality, ensuring a smoother onboarding experience.

Introduction

Bad documentation is a significant barrier to developer adoption, impacting usability and product credibility. It can lead to confusion, increased support tickets, and ultimately, abandonment of the product. Bad documentation is defined as content that lacks clarity, structure, or relevance, making it difficult for users to understand and implement the product effectively. This article explores common documentation pitfalls, their implications, and how to fix them to improve user experience and trust.

Common Documentation Pitfalls

1. No Actual Documentation or Broken Docs

The absence of documentation is the most damaging issue. Developers expect integration guides and setup instructions. Without them, they face immediate disruption, leading to low user retention.

2. Outdated Documentation

Documentation that doesn't match the current product version erodes trust. Users waste time troubleshooting outdated information, leading to onboarding drop-offs and increased support tickets.

3. Overwhelming Volume Without Flow

When documentation is cluttered and lacks a logical structure, users can become lost. This confusion slows onboarding and increases frustration, making it hard for users to find critical information.

4. Writing for Experts Instead of Beginners

Assuming prior knowledge can alienate new users. Documentation should be accessible to all skill levels, providing context and explanations for each component.

5. Accessibility Issues

If documentation is hard to find or navigate, it fails its purpose. Poorly indexed or scattered content leads to increased support tickets and slows onboarding.

6. The One-Trick Pony

Documentation that only provides reference material without context is ineffective. Users need to understand why actions are necessary and how they fit into a workflow.

7. Not Following a Great Documentation Model

Learning from effective documentation can save time and prevent common errors. Teams should adopt proven patterns to enhance their own documentation.

How It Works / Process

Input: Identify documentation gaps through user feedback and community complaints. Gather insights from developers who have faced challenges.
Processing: Analyze the documentation for clarity, structure, and relevance. Look for missing integration guides, outdated CLI commands, or overwhelming information.
Output: Revise the documentation to include clear, step-by-step instructions, updated information, and contextual explanations. Ensure that it caters to both beginners and experienced users.
Edge Cases: Consider scenarios where users may have unique needs or backgrounds. Ensure that the documentation is flexible enough to accommodate various skill levels and use cases.

Practical Example / Use Case

Consider a B2B SaaS platform that initially had no integration documentation. Developers struggled to connect the platform with existing systems, leading to high dropout rates.

To address this, the documentation team created comprehensive integration guides, including clear steps and real-world use cases. They also updated CLI documentation to reflect current commands and provided examples of expected outputs.

As a result, developers found the documentation reliable and easy to follow, significantly reducing onboarding friction and increasing user retention.

Key Takeaways

Bad documentation can severely hinder developer adoption and trust.
Outdated or missing documentation leads to increased support tickets and onboarding drop-offs.
Clear, structured documentation improves user experience and reduces confusion.
Writing for all skill levels ensures that both beginners and experts can effectively use the documentation.
Learning from successful documentation models can streamline the improvement process.

FAQ

What are the most common documentation pitfalls?

Common pitfalls include missing documentation, outdated content, overwhelming information, and writing that assumes expert knowledge. Each of these issues can significantly disrupt the user experience.

How can I improve my product documentation?

Focus on clarity, structure, and accessibility. Ensure that documentation is regularly updated, easy to navigate, and provides context for all users, regardless of their experience level.

Why is documentation important for developers?

Documentation serves as the primary resource for developers to understand how to implement and use a product effectively. Good documentation minimizes support dependency and enhances user confidence.

What should I include in my documentation?

Include clear integration guides, updated CLI commands, contextual explanations, and real-world use cases. This will help users understand the "why" behind each action and improve their overall experience.

Conclusion

Improving documentation is essential for fostering developer trust and enhancing user experience. By addressing common pitfalls and implementing effective strategies, organizations can create documentation that not only informs but also empowers users, paving the way for successful product adoption.

Bad Documentation Examples: Why Developers Drop Off | Fixes

Tech code — Mon, 15 Dec 2025 20:16:23 +0000

Bad documentation can severely hinder developer adoption and engagement. In this article, you will learn about common pitfalls in product documentation and how to address them effectively to enhance usability and trust.

Introduction

Bad documentation is a significant barrier to developer adoption, often leading to frustration and abandonment of products. It encompasses issues such as missing integration guides, outdated CLI references, and poorly structured content. Bad documentation is defined as any content that fails to provide clear, actionable guidance for users, ultimately disrupting their onboarding experience. This article explores common documentation pitfalls and offers solutions to improve clarity and usability.

Concept Explanation

Effective documentation is crucial for guiding developers through the integration and usage of a product. It should:

Provide Context: Explain not just the "how," but also the "why" behind each step.
Maintain Structure: Organize content logically to facilitate easy navigation.
Be Up-to-Date: Regularly revise documentation to align with product updates.
Cater to All Skill Levels: Avoid jargon and assume no prior knowledge from users.

By addressing these aspects, documentation can significantly enhance the user experience and reduce support requests.

How It Works / Process

Input: Gather user feedback and common complaints regarding existing documentation.
Processing: Analyze the feedback to identify specific issues such as outdated content, lack of structure, or missing information.
Output: Revise documentation to include:
- Comprehensive integration guides.
- Updated CLI references with clear examples.
- Structured content that flows logically.
Edge Cases: Consider scenarios where users may have varying levels of expertise. Documentation should be accessible to both beginners and experienced developers.

By following these steps, teams can create documentation that not only meets user needs but also fosters trust and confidence in the product.

Practical Example / Use Case

Consider a B2B SaaS company that offers a cloud cost management tool. Initially, their documentation was sparse, lacking integration guides and clear instructions. Developers struggled to connect the tool to their existing systems, leading to frustration and increased support tickets.

To address this, the company implemented a structured documentation system. They created detailed integration guides, updated CLI commands, and included real-world use cases. This transformation resulted in a significant reduction in onboarding time and support requests, as developers could now find the information they needed quickly and easily.

Key Takeaways

Bad documentation can severely disrupt developer onboarding and increase support requests.
Effective documentation should provide context, structure, and be regularly updated.
It is essential to cater to users of all skill levels, avoiding jargon and assumptions.
A systematic approach to revising documentation can significantly enhance user experience.
Learning from successful documentation examples can streamline the improvement process.

FAQ

What are the signs of bad documentation?

Bad documentation often includes missing information, outdated content, poor organization, and jargon-heavy language that assumes expert knowledge. These issues can lead to increased support requests and user frustration.

How can I improve my documentation?

To improve documentation, gather user feedback, update outdated content, structure information logically, and ensure it is accessible to users of all skill levels. Regular revisions are essential to maintain relevance.

Why is context important in documentation?

Context helps users understand not only how to perform tasks but also why those tasks matter. This understanding fosters trust and confidence in the product, leading to better adoption rates.

How often should documentation be updated?

Documentation should be updated regularly, especially after product updates or user feedback. A good practice is to review it at least quarterly to ensure accuracy and relevance.

Conclusion

Improving documentation is vital for enhancing developer adoption and satisfaction. By addressing common pitfalls and implementing structured, clear, and context-rich content, organizations can significantly reduce onboarding friction and build trust with their users. Regular updates and user feedback are essential to maintain effective documentation.

Bad Documentation Examples: Why Developers Drop Off | Fixes

Tech code — Mon, 15 Dec 2025 13:09:20 +0000

Bad Documentation Examples: Why Developers Drop Off | Fixes

Overview

TL;DR

Bad documentation significantly hinders developer adoption by obstructing the transition from interest to implementation. Issues like missing integration guides, outdated CLI instructions, and unstructured content lead to increased onboarding friction and support tickets. Effective documentation minimizes guesswork, enhances usability, and builds trust.

Importance of Good Documentation

Documentation is often the first real interaction users have with a product. If it fails to provide clear guidance, users may either inundate support with basic questions or abandon the platform altogether. Strong documentation should offer:

Clear explanations of processes
The “why” and “how” behind actions
Reliable troubleshooting steps

Developer Learning Preferences

Nearly 68% of developers rely on technical documentation for learning. They seek precise commands, examples, and expected outputs. Poor documentation can lead to:

Increased onboarding friction
Higher support workload
Erosion of developer trust

Real Developer Community Complaints

Developers have voiced several complaints regarding poor documentation:

Missing fields and unclear authentication flows can extend simple tasks into lengthy processes.
Poor organization or jargon-heavy content makes it easier to read raw code than documentation.

These complaints indicate systemic issues in documentation practices.

7 Common Bad Documentation Examples

1. No Actual Documentation or Broken Docs

The absence of documentation is one of the most damaging pitfalls. Developers expect integration guides and clear setup instructions. Without these, they face immediate disruption.

Example: A partnership with a cost optimization platform revealed gaps in documentation, including missing integration guides. This led to low user retention and broken onboarding.

Fix: Create comprehensive integration documentation with clear steps and use cases. Update CLI documentation to include accurate commands and examples.

2. Outdated Documentation

Outdated documentation breaks developer trust. When documentation does not match the current product, users waste time troubleshooting.

Example: A customer’s documentation, created during early development, became outdated and lacked context, leading to confusion.

Fix: Regularly update documentation to align with current product capabilities. Ensure CLI commands and examples reflect real-world usage.

3. Overwhelming Volume Without Flow

Excessive information without clear structure can overwhelm users. Developers may struggle to navigate multiple pages, slowing onboarding.

Example: Scattered documentation across pages led to confusion, with users missing critical guidance.

Fix: Centralize documentation and establish a logical flow. Organize content by job persona to ensure relevant guidance is easily accessible.

4. Writing for Experts Instead of Beginners

Documentation that assumes expert knowledge can alienate beginners. This creates a communication gap, leading to slower onboarding and increased errors.

Example: Documentation for an AI-powered Kubernetes optimization platform lacked context, making it difficult for beginners to understand.

Fix: Add context to every component and feature. Provide step-by-step examples and guided workflows to assist first-time users.

5. Accessibility Issues

Documentation that is hard to locate or navigate fails its purpose. Poor discoverability increases support tickets and slows onboarding.

Example: A customer’s documentation was poorly indexed and scattered, making key features hard to find.

Fix: Centralize documentation into a structured hub with clear navigation paths to improve discoverability.

6. The One-Trick Pony

Documentation that only lists commands or workflows without context is ineffective. Developers need to understand the intent behind actions.

Example: An AI agent platform provided CLI documentation that lacked explanations, forcing users to guess relevance.

Fix: Include context, expected outcomes, and real-world use cases in documentation. This transforms static content into actionable guidance.

7. Not Following Great Documentation

Learning from effective documentation can save time and prevent errors. Teams should adopt proven patterns rather than reinventing the wheel.

Fix: Analyze high-performing documentation examples to identify best practices and implement them in your own documentation.

Conclusion

Bad documentation can severely impact developer adoption and trust. By addressing common pitfalls and implementing effective documentation strategies, teams can enhance usability, improve onboarding experiences, and ultimately drive product success.

Frequently Asked Questions

What are the signs of bad documentation?
- Missing guides, outdated content, poor organization, and lack of context are key indicators.
How can I improve my documentation?
- Regularly update content, ensure clear structure, and provide context for all features and commands.
Why is documentation important for developers?
- Good documentation serves as a reliable resource for learning and troubleshooting, facilitating smoother onboarding and implementation.