How to Write Technical Blog Posts with AI: Research, Code Validation, and Human Review

A technical post contains three code samples, but none has been executed. Readers copy them, hit errors, and discover that the problem was never the polish. The facts and code never passed a gate.

An AI draft can look complete while guessing versions, command arguments, and output formats. One project declares "type": "module" in package.json, but its example calls require directly. Another post says that GitHub Actions includes “2,000 minutes per month” without explaining that this is an allowance for private repositories on a particular plan.

Technical blogging is not a matter of giving a topic to a model and polishing the result. Start with sources and executable evidence, let AI organize the explanation, and have a person review the facts, code, and style. The workflow below assigns a gate and an owner to each stage so that claims remain accurate, code remains runnable, and conclusions remain reproducible.

Research Before Asking AI to Draft

What must be researched, and what can AI draft?

The first decision in AI-assisted technical writing is straightforward: which facts must come from outside sources, and which parts can the model organize?

Three categories help make that decision.

Research first when the article depends on versions, changed API fields, documented limits, prices or quotas, and security configuration. An error in any of these can break a reader’s project or create an unexpected bill. For example, current Next.js documentation uses the turbopack configuration key, while versions 13.0.0 through 15.2.x used experimental.turbo. A recommendation that omits the applicable version may send readers to an incompatible configuration.

AI may draft general concepts, framework usage, best practices, and common mistakes, but a reviewer still needs to check them. A model will often produce a plausible explanation of React hooks, for example, but rule counts, naming conventions, and version differences should still be checked against the official documentation.

AI can handle structure, prose editing, and formatting on its own. Rephrasing a technical explanation in plainer language or combining related paragraphs does not normally require new research.

The three categories compare as follows:

Research category	Typical content	Gate strength	Where it belongs
Research first	Versions, API fields, prices or quotas, security settings	High: extract from official documentation and mark [VERIFY]	Complete during planning; recheck on the writing date
AI draft + review	General concepts, framework usage, best practices	Medium: AI draft, then compare with official documentation	Draft during writing; verify during review
AI can organize	Structure, prose, formatting	Low: no additional research normally required	Complete during drafting

A simple decision tree:

You encounter content of type X
  ↓
Does it involve a version, API, price, or security setting?
  ├─ Yes → Extract it from official documentation, mark [VERIFY], and recheck it on the writing date
  └─ No → Does it describe a technical rule or best practice?
      ├─ Yes → Let AI draft it, then verify it against official documentation during review
      └─ No → Let AI organize the explanation

How to carry research into the writing input

After research, put the results into the writing input so that the drafting stage can use them directly.

Extract high-confidence sources from research.md, especially official documentation marked high. Examples include Google Search Central’s guidance on helpful content, GitHub’s Node.js CI examples, and the Astro Content Collections documentation.

Mark changing facts with [VERIFY]. Examples include “The included GitHub Actions allowance for private repositories depends on the account plan [VERIFY]” and “Check whether the target Node version is still supported [VERIFY].”

Add source cards, command output, and review results to the source_cards and risk_notes fields of the outline input:

{
  "source_cards": [
    {
      "url": "https://developers.google.com/search/docs/fundamentals/creating-helpful-content",
      "type": "official/docs",
      "confidence": "high",
      "usable_info": "Content should add original information and a complete explanation instead of relying primarily on large-scale automation"
    }
  ],
  "risk_notes": [
    {
      "fact": "GitHub Actions included usage",
      "status": "[VERIFY]",
      "check_date": "2026-06-24",
      "source": "https://docs.github.com/en/billing/managing-billing-for-github-actions"
    }
  ]
}

Once these markers exist, the drafting stage does not need to repeat the entire research process. It only needs to recheck the changing facts identified by the handoff.

Code Examples Must Run, Not Merely Look Runnable

Four code-validation scenarios

Technical code samples often look plausible while failing in a real project. Once readers copy them and encounter an error, the article loses their trust.

Code validation falls into four scenarios.

Local execution covers installation commands, configuration examples, and small scripts, such as npm install, git clone, or a configuration edit. Run these commands locally and retain the output.

CI testing covers build commands, test commands, and environment dependencies, such as npm ci, npm run build, and npm test in GitHub Actions. CI is useful because it makes the environment repeatable.

Version validation covers the Node version, dependency versions, and API versions, including .nvmrc, package.json, and endpoint changes. Record the version and explain relevant differences. Environment consistency covers differences among development, production, and CI, including environment variables, Docker images, and operating systems. Name the environment so that readers do not apply one environment’s result to another.

The four scenarios compare as follows:

Validation scenario	Typical content	Validation method	Required evidence
Local execution	Install commands, configuration files	Execute locally	Command output text or a screenshot
CI testing	Build and test commands	GitHub Actions or another CI service	CI log or build-result screenshot
Version validation	Node or dependency versions	Version-check command	node --version output plus a version note
Environment consistency	Environment variables, Docker	Test multiple environments or state the tested one	Environment label plus conditions

How to record execution evidence

Every code example needs execution evidence. “It ran successfully” is not evidence. The commands and output below show only the format of an evidence record; they are not reusable test results. Replace them with the actual versions and logs from the target project.

Example command record for a Node.js CI task:

# Local environment: macOS + Node 18.20.0 LTS
$ node --version
v18.20.0

# CI environment: GitHub Actions
$ npm ci
added 245 packages in 12s

$ npm run build
✓ Built in 1.23s

$ npm test
✓ 12 tests passed

Output comparison:

Correct: include a screenshot or text output, the version, and the relevant result.

Incorrect: say only “it ran successfully” without recording any output.

Use fenced code blocks with a language identifier such as bash or typescript. Collapse long output or show only the relevant lines. For a multi-step command, name the environment—local, CI, or Docker. For version checks, retain the output from node --version or npm --version.

For example:

# Execution environment: macOS + Node 18.20.0
$ npm install
added 124 packages in 8s

$ node --version
v18.20.0

When build output is long, show the relevant portion:

$ npm run build
✓ Built in 1.23s
  ├─ dist/index.html
  ├─ dist/assets/index.js
  └─ dist/assets/index.css

GitHub documents fenced code blocks and syntax highlighting in Creating and highlighting code blocks. A technical article should preserve copyable, inspectable code instead of disguising code as prose.

Human Review Checks Facts, Code, and Structure

Fact review: trace versions, arguments, and prices

Human review is not merely prose editing. It checks three layers: facts, code, and structure. Treating review as a wording pass misses incorrect versions, invalid arguments, and conclusions that do not match the code.

Fact review is about traceability. Check every version, API field, command argument, configuration value, price or quota, and release date against official documentation or an actual execution record.

Use a checklist like this:

Item	Review method	Failure signal	Acceptable evidence
Version	Compare with an official release or documentation	The version does not exist, or the described feature is wrong	Official link plus node --version output
Command argument	Compare with official CLI documentation	The argument does not exist or uses the wrong format	Official link plus actual command output
API field	Compare with official API documentation	The field is missing or has the wrong type	Official link plus a real request example
Price or quota	Compare with the official pricing page	Wrong price or missing public/private conditions	Official link plus applicable conditions
Release date	Compare with the official announcement or blog	Wrong date or nonexistent event	Official announcement link

An incorrect example:

The project declares "type": "module" in package.json, but the sample uses CommonJS require directly without changing to .cjs or explaining the module boundary.

Another incorrect example:

The article says “GitHub Actions has only 2,000 free minutes per month” without noting that standard GitHub-hosted runners are free for public repositories, while the allowance for private repositories depends on the account plan.

More accurate wording:

“Node 18 supports both ES modules and CommonJS. .mjs, .cjs, and the type field in package.json affect how a file is interpreted. This execution record used Node 18.20.0 and retained the output of node --version (source: Node.js documentation).”

“As of July 26, 2026, standard GitHub-hosted runners are free for public repositories. Private repositories receive included minutes by account plan—for example, 2,000 minutes with GitHub Free and 3,000 with GitHub Pro (source: GitHub Actions billing).”

Code review: runnable commands, matching output, named environment

Code review asks three questions: does the command run, does the output support the text, and is the environment explicit?

Item	Review method	Failure signal	Acceptable evidence
Runnable command	Run locally or in CI	Error or missing dependency	Execution log or screenshot
Matching output	Compare output with the prose	Output contradicts the article	Description and recorded output agree
Named environment	Inspect environment notes	Missing Node version or operating system	Node 18.20.0 + macOS
Dependency version	Check package.json	Dependency version conflicts with the article	package.json or version-check output

An incorrect example:

The text says that the build produced three files, but npm run build actually lists five.

The text says the code ran locally, but the sample depends on Docker and never mentions that requirement.

Better evidence:

The prose matches the log: “npm run build produced three files: index.html, index.js, and index.css.”

The environment is explicit: “Tested on macOS with Node 18.20.0. Linux and Windows may require path changes.”

Structure and style review: headings, internal links, and AI residue

Structure and style review checks whether H2 and H3 sections match the approved structure, whether internal links appear where planned, and whether generic AI phrasing has been removed.

Item	Review method	Failure signal	Acceptable result
H2/H3 consistency	Compare with outline.md	Missing or unexpected sections	Record why the structure changed
Internal-link placement	Compare with the linking plan	Missing link or misleading anchor	Place the planned link with descriptive text
AI-like phrasing	Compare with anti-ai-words.json	Empty claims or vague attribution	Replace with a concrete fact or remove it

The site’s anti-ai-words.json groups expressions that should be avoided. During review, replace or remove empty claims, vague attribution, and excessive promises.

An incorrect example is a generic era-setting opener.

Another is an empty promise such as “This article provides a comprehensive analysis.”

A better opening goes directly to the problem: “AI-assisted technical writing starts with one decision: which facts must come from outside sources?”

A better promise is testable: “This workflow assigns a gate to research, validation, and review.”

Close the Workflow with Pre-Publication QA

Pre-publication QA checklist

Finishing a draft does not make it publishable. Pre-publication QA is the last gate. It checks research markers, code evidence, fact traceability, structure, internal links, AI residue, and image assets.

Item	Check	Passing condition	Failure response
Research markers cleared	Search for [VERIFY]	No unresolved marker remains	Return to research and verify it
Code examples validated	Compare with execution logs	Every example has evidence	Return to code validation
Facts traceable	Compare with source cards	Every important fact has a source or qualification	Add a source or remove the claim
Structure consistent	Compare with outline.md	H2/H3 matches, or changes are explained	Update the structure record or explain the change
Internal links placed	Compare with the linking plan	Links exist and anchors are accurate	Add the link or revise the plan
AI residue removed	Compare with anti-ai-words.json	No generic AI filler remains	Rewrite or remove it
Images available	Compare the image list with Markdown paths	Every referenced asset exists and is processed	Upload the image or fix the path

Status meanings:

Pass: ready to publish.

Pending: a source or claim still needs review.

Fail: return to research, validation, or drafting.

Review each item separately. Mark a problem as soon as it appears. Update the task to “ready to publish” only after every item passes.

How to send a failed check back

A failed QA item returns to the stage that owns the issue. It is not waived.

A factual error goes back to research. Add an official source, remove an unsupported claim, or mark and recheck a changing fact.

A code error goes back to validation. Rerun the command, save the output, update the sample, and name the execution environment.

A structural mismatch requires either an updated structure record or an explicit explanation of which H2 or H3 changed and why.

A missing internal link goes back to the linking plan. Find the correct article in the site inventory and use descriptive anchor text rather than “click here.”

AI residue goes back to editing. Replace flagged wording, and rewrite the sentence when a direct replacement would remain vague.

Example:

QA finds that a GitHub Actions allowance lacks its public/private condition
  ↓
Mark the item as failed
  ↓
Return to research
  ↓
Add the official billing source and state the applicable conditions
  ↓
Run QA again

The point of a return path is accountability. A final reviewer should be able to see which stage fixed the problem instead of inheriting an unexplained change.

Seven Signals That an Article Has Drifted from the Facts

The seven signals

Factual drift accumulates. These signals help writers and reviewers catch it before publication.

Signal 1: an unsourced assertion. The article says “latest version,” “official recommendation,” or “best practice” without linking to the relevant source. For example, it says a Turbopack configuration key works in every Next.js version but never cites the documentation for those versions.

Signal 2: code that was never run. The sample has no real output or log and says only “it worked.”

Signal 3: a version or parameter is misclassified. The version may exist, but its release line or support status is wrong; command arguments and API endpoints may also have changed. Calling Node 20.1.0 an LTS release is one example: it was a Current release.

Signal 4: the environment does not match. The evidence names one environment, while the sample depends on behavior validated only somewhere else.

Signal 5: the conclusion cannot be reproduced. The post claims a noticeable performance improvement without a method, dataset, or reproduction steps.

Signal 6: an internal link is broken. The article points to /posts/ai/ai-xxx, but no such route exists.

Signal 7: generic AI phrasing hides the gap. An empty promise such as “a comprehensive analysis” replaces a source or a concrete result.

Examples:

Signal	Bad example	Problem
Unsourced assertion	“This Turbopack key works in every Next.js version”	No official documentation for the applicable versions
Unexecuted code	“Run npm install; it succeeds”	No execution evidence
Wrong version	“Node 20.1.0 LTS”	Version 20.1.0 was Current, not LTS
Environment mismatch	The record names an old environment, but the code depends on behavior tested only elsewhere	Version and validation environment do not agree
Irreproducible conclusion	“Performance improved significantly”	No method or data
Broken internal link	Link to /posts/ai/ai-xxx	Route does not exist
AI residue	“A comprehensive analysis of AI writing”	Vague promise

When a signal appears, mark it [VERIFY] and return it to the responsible stage.

An unsourced assertion returns to research for a primary source or deletion. Unexecuted code returns to validation. A wrong version returns to an official release record. An environment mismatch needs a corrected environment note or a removed claim. An irreproducible conclusion needs a method, dataset, and steps—or removal. A broken internal link needs a real route. Generic phrasing needs a concrete fact or deletion.

The important action is immediate return. Delaying the fix allows several small uncertainties to become one untraceable article.

How to Write Honestly Without the Full Test Environment

Three honest approaches

Sometimes the full environment is unavailable: a paid service, a complex cluster, a specific operating system, or particular hardware. Do not fabricate evidence to fill the gap. Use one of three approaches.

First, state the conditions and limits. Name the tested version and explain which versions may differ, or state that testing covered only the free tier. For example: “The sample was validated only on Node 18.20.0; other versions may differ (see the Node.js documentation).”

Second, provide an alternative validation method. Offer a minimal reproduction, mock data, or an official issue record. For example: “No Kubernetes cluster was available, so this section provides only a minimal reproduction. It still needs validation in a real cluster.”

Third, admit what remains unverified. Write “This performance conclusion was not reproduced in the current environment” or remove the assertion entirely.

The difference is visible in a table:

Scenario	Dishonest wording	Honest wording
Version difference	“Every version supports it”	“Validated on Node 18.20.0; other versions may differ (see the Node.js documentation)”
Environment difference	“It ran locally”	“Tested on macOS with Node 18.20.0; Linux, Windows, or another Node version may require changes”
Paid service	“It is free”	“Testing covered only the free tier; paid-tier behavior may differ (see the official pricing page)”
Unverified assertion	“Performance improved significantly”	“The current environment did not reproduce this performance conclusion, so it is not presented as a confirmed result”

Acceptable examples:

“This test used the Cloudflare Workers free tier, which currently includes 100,000 requests per day. Paid-tier behavior can differ; check the official pricing page.”

“No Kubernetes cluster was available. The article provides a minimal reproduction, which still needs testing in a real cluster with the relevant Pod resource limits and network settings.”

“There is no large-project benchmark here, so the article makes no claim about Turbopack build performance. Measure a baseline and comparison in your own project.”

Unacceptable examples:

“Cloudflare Workers is free.” The quota is missing.

“It works in every environment.” The environments are unnamed.

“Performance improved significantly.” There is no method or data.

Google Search Central recommends original information, a complete explanation, and useful analysis in Creating helpful, reliable, people-first content. Honest qualification does not lower the standard. It tells readers which parts were validated and which still require their own test.

When to Publish and When to Rewrite

Publication decision tree

The decision is not based on word count or visual completeness. It depends on whether research, validation, review, and QA passed.

Research: if every high-confidence source is available and changing facts are marked, continue to code validation. If a core source is missing, research it first.

Code validation: if every code example ran, continue to review. If a sample failed, fix or remove it. If it cannot be tested, state the limits or delete it.

Human review: if facts are traceable, continue to QA. If a fact has no source, add one or remove the claim. A structural change with an explanation may continue; an unexplained structural drift returns to planning.

Pre-publication QA: all checks passing means the article can proceed. A pending item needs review. A failed item returns to its owning stage.

An article can proceed when research is complete, changing facts have been rechecked, code examples have execution evidence, human review confirms traceability and structure, generic AI phrasing is removed, and every QA item passes.

It needs more work when a source, execution record, internal link, or style cleanup is missing.

It must be rewritten when a core version, parameter, price, or other fact is wrong; when a central conclusion cannot be reproduced; or when the structure no longer serves the agreed task and has no recorded reason.

The workflow has a gate at every stage. A failure returns to its source instead of being carried into publication.

Prioritize returns in this order:

Fix or remove factual errors first. Code errors come next because readers may copy them. Structural drift and missing links are lower priority, but they still need resolution before publication.

Further Reading

If you need to constrain an AI tool with project context first, continue with using CLAUDE.md to keep AI coding on track. To package writing and review steps as reusable capabilities, see building workflows with Claude Code Skills.

The site also has an AI writing workflow for general content creators. That article focuses on speed; this one focuses on technical facts, execution evidence, and publication gates. They can be used together.