$ cat article/ai-authoring-workflow.md

AI-Assisted Authoring with Hype

# @ Cory LaNou ~ 7 min
#tutorial #ai #authoring #workflow #claude #hype

AI-Assisted Authoring with Hype

AI assistants are transforming how we write code. But when it comes to technical documentation, there's a trust problem: AI can generate plausible-looking code examples that don't actually work. Hype solves this by validating everything at build time — making AI-generated content trustworthy through automated verification.

This guide shows how to combine AI authoring with Hype's validation to write better documentation, faster.

The Trust Problem

When an AI generates a code example for your documentation, it might:

  • Use an API that was renamed two versions ago
  • Import a package that doesn't exist
  • Show output that doesn't match what the code actually produces
  • Use syntax that's almost right but won't compile

In a regular Markdown file, these errors are invisible until a reader tries the code. In a Hype document, the build catches them immediately.

The Workflow

The AI-assisted Hype authoring workflow has three phases:

  1. Generate — AI writes the prose and code examples
  2. Validate — Hype builds the document, catching errors
  3. Iterate — AI fixes what the build caught

This is fundamentally different from the "generate and ship" workflow that produces unreliable documentation.

Phase 1: Generate the Structure

Start by asking your AI assistant to create the document structure with real source files. The key instruction: code examples must be separate .go files, not inline code blocks.

For example, ask Claude:

"Write a tutorial about Go's context package. Create the example code as separate Go files in a src/ directory, and reference them with Hype's include syntax."

The AI generates:

context-tutorial/
├── hype.md
└── src/
    ├── basic/main.go
    ├── timeout/main.go
    ├── cancel/main.go
    └── values/main.go

Each source file is a complete, runnable program. The hype.md references them with <code> and <go> tags.

Phase 2: Build and Catch Errors

Run the build:

hype export -format markdown -f hype.md > /dev/null

The build might fail with something like:

Error: filepath: hype.md
document: Context Tutorial
execute error: src/timeout/main.go:15:
    ctx.WithTimeout undefined (type context.Context has no method WithTimeout)

The AI used ctx.WithTimeout() instead of context.WithTimeout(). A plausible mistake that a human reviewer might miss, but the compiler catches instantly.

Phase 3: Fix and Rebuild

Give the error back to the AI:

"The build failed. context.WithTimeout is a package-level function, not a method on Context. Fix src/timeout/main.go."

The AI fixes the code. You rebuild. The cycle continues until the build succeeds, at which point every code example in the document is verified correct.

Practical Example: Writing a Package Tutorial

Let's walk through writing a complete tutorial using this workflow.

Step 1: Set Up the Project

mkdir errors-tutorial && cd errors-tutorial
mkdir -p src/{wrapping,sentinel,custom,unwrap}

Step 2: AI Generates the Content

Ask the AI to write the tutorial. Provide these constraints:

  • Each concept gets its own subdirectory under src/
  • Every Go file must be a complete package main with a main() function
  • Use <go> tags to both show the code and run it
  • Use snippets to highlight specific parts

The AI generates hype.md:

# Effective Error Handling in Go

## Wrapping Errors

The `%w` verb in `fmt.Errorf` wraps an error, preserving the
original for inspection:

<go src="src/wrapping" run="." code="main.go#wrap-example"></go>

## Sentinel Errors

Define package-level sentinel errors for conditions callers
need to check:

<go src="src/sentinel" run="." code="main.go#sentinel-def"></go>

## Custom Error Types

Implement the `error` interface for errors that carry
structured data:

<go src="src/custom" run="." code="main.go"></go>

## Unwrapping and Checking

Use `errors.Is` and `errors.As` to inspect wrapped errors:

<go src="src/unwrap" run="." code="main.go"></go>

And the source files:

// src/wrapping/main.go
package main

import (
    "errors"
    "fmt"
)

// snippet: wrap-example
func readConfig(path string) error {
    err := errors.New("file not found")
    return fmt.Errorf("readConfig(%q): %w", path, err)
}
// snippet: wrap-example

func main() {
    err := readConfig("/etc/app.conf")
    fmt.Println(err)
    fmt.Println("Unwrapped:", errors.Unwrap(err))
}

// src/sentinel/main.go
package main

import (
    "errors"
    "fmt"
)

// snippet: sentinel-def
var (
    ErrNotFound     = errors.New("resource not found")
    ErrUnauthorized = errors.New("unauthorized access")
    ErrRateLimit    = errors.New("rate limit exceeded")
)
// snippet: sentinel-def

func findUser(id int) error {
    if id <= 0 {
        return fmt.Errorf("findUser: %w", ErrNotFound)
    }
    return nil
}

func main() {
    err := findUser(-1)
    if errors.Is(err, ErrNotFound) {
        fmt.Println("User not found (expected)")
    }
}

Step 3: Build

hype export -format markdown -f hype.md

If everything compiles and runs, you have a validated tutorial. If not, the error tells you exactly what to fix.

Step 4: Review and Refine

With the code validated, focus your review on:

  • Prose quality — is the explanation clear and accurate?
  • Pedagogical flow — do concepts build on each other logically?
  • Completeness — are edge cases covered?

You don't need to manually verify that code examples work. The build already did that.

Tips for AI-Assisted Hype Authoring

Give the AI the Right Constraints

The most important instruction is to keep code in separate files:

"Write code examples as standalone Go files in src/ subdirectories. Each must be a complete program that compiles and runs. Reference them with Hype <go> and <code> tags in the markdown."

Use Snippets to Focus

AI-generated examples often include boilerplate. Use snippets to show only the relevant part:

"Add snippet markers around the key function so the tutorial can show just that function while the full file still compiles."

Let the Build Be the Reviewer

Don't spend time manually checking code examples. Build the document. If it passes, the code is correct. If it fails, the error message tells you exactly what's wrong.

Iterate Quickly

The AI → build → fix cycle is fast:

  1. AI generates or modifies a file
  2. hype export runs in seconds
  3. Error goes back to the AI
  4. Repeat until green

A typical tutorial with 5-10 code examples goes from first draft to fully validated in a few minutes.

Version Pin Your Examples

When the AI generates code, ask it to use specific versions:

"Use Go 1.22's range-over-func feature. Make sure the go.mod specifies go 1.22."

This ensures the examples are reproducible and won't break with Go version changes.

Stabilizing Dynamic Output

AI assistants often produce examples with dynamic output (timestamps, UUIDs, etc.). Use Hype's replace attributes to stabilize:

<cmd exec="go run ./src/timestamp"
     replace-1="\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}"
     replace-1-with="2024-01-15T10:30:00"></cmd>

The command runs (validating it works), but the output is deterministic in the final document. No more noisy diffs from regenerating docs.

CI Integration

Add validation to your CI pipeline so AI-generated docs are checked on every push:

name: Validate Documentation
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
      - run: go install github.com/gopherguides/hype/cmd/hype@main

      - name: Build all tutorials
        run: |
          for doc in */hype.md; do
            dir=$(dirname "$doc")
            echo "Building ${dir}..."
            (cd "$dir" && hype export -format markdown -f hype.md > /dev/null)
          done

This catches regressions: if a Go update breaks an example, the CI build fails and you know exactly which document needs updating.

What This Unlocks

The combination of AI authoring speed and Hype validation changes what's practical:

  • Write a tutorial in minutes, not hours — AI generates the structure and examples, Hype verifies correctness
  • Update docs with confidence — regenerate after dependency changes, the build catches every broken example
  • Scale documentation — producing 10 validated tutorials is only slightly more work than producing 1
  • Trust AI-generated content — the compiler is the reviewer, not a human scanning for plausible-but-wrong code

Key Takeaways

  • AI generates, Hype validates — plausible-looking code is verified by the compiler
  • Separate files, not inline code — keep examples as real Go files that compile independently
  • Fast iteration cycles — generate, build, fix, repeat until green
  • Focus human review on prose — let the build handle code correctness
  • CI catches regressions — automated builds surface broken examples from dependency changes
  • Stabilize dynamic output — replace patterns keep regenerated docs diff-friendly

Get Started

brew install gopherguides/tap/hype

mkdir my-tutorial && cd my-tutorial
mkdir -p src/example

Write your first AI-assisted tutorial. Ask the AI to create a Go example as a separate file, reference it with a <go> tag, and build. When the build passes, you have documentation you can trust.