How Mintlify uses Claude Code as a technical writing assistant

As a solo technical writer at Mintlify, I'm always looking for ways to improve my workflows and empower other people on my team to contribute to the docs. I also want to take a vacation without blocking docs ships for a week and a half.

This blog post is adapted from my tips for the team while I'm out of office.

Use Claude Code as a technical writing assistant

I've been using Claude Code as my writing assistant since it launched. Claude Code can read your codebase, analyze Git branches, search existing documentation, and maintain context about your project's specific style and requirements. I've come to prefer Claude Code over other AI tools for a few reasons.

• I like running Claude in the terminal and it fits in well with how I like to work.
• I can easily configure and share CLAUDE.md files for projects so that my team has shared guidelines.
• And I've found that it generates better content than most other tools.

I'll warn you now though, it's not quite as easy as typing "write this" and receiving perfectly polished docs. For someone who might not consider themselves a writer, but is an expert on the code they just shipped, Claude can help plan and draft documentation, making them feel confident about their writing. For technical writers, Claude Code can help you get information about recent ships or in progress work when SMEs are unavailable to discuss details.

You are smarter than Claude

If you remember only one thing from this post, remember this: don't publish something just because Claude suggested it.

Always verify any docs changes with your own expertise or by getting someone who is an expert to review.

Setting up Claude Code

Set up Claude Code by running the following commands in your terminal:

npm install -g @anthropic-ai/claude-code
cd path/to/docs
claude

Make sure Claude Code is properly installed by asking it a question, having it tell you a joke, or whatever you want. If it responds, we're good to go.

Create a CLAUDE.md file

To train Claude as your technical writing partner, create a CLAUDE.md file. This configuration file gives context, sets quality standards, and defines how Claude interacts with you.

Think of it like onboarding a new team member. You want to explain the most important things up front, and you don't want them searching through a 100-page manual before starting every task.

That last point matters more than it might seem. Claude and other LLMs have improved since I first wrote about this and our understanding of organizing context has evolved too. Less is more for Claude. A long CLAUDE.md gets ignored or garbled, which could give you worse results than no CLAUDE.md at all.

The current consensus is that your CLAUDE.md should be focused. Anything that can be enforced programmatically shouldn't rely on Claude following an instruction.

What to include in your CLAUDE.md:

• How you want Claude to behave as a collaborator (ask for clarification, push back, don't make things up)
• Project structure context (file format, config files, component library)
• Core content principles that require judgment
• Any hard constraints that Claude should never break

What belongs elsewhere:

• Style and tone rules → consider a deterministic prose linter like Vale
• Git workflow rules → enforce them programmatically with hooks
• Context-specific workflow instructions → skills (covered below)

CLAUDE.md example

Here's what a lean CLAUDE.md might look like:

# Mintlify documentation

## Working relationship

- Push back on ideas with reasoning—this leads to better docs
- Always ask for clarification rather than making assumptions
- Never lie, guess, or make up information

## Project context

- Format: MDX files with YAML frontmatter
- Config: docs.json for navigation, theme, settings
- Components: Mintlify components (see existing pages for patterns)

## Content strategy

- Document just enough for user success—not too much, not too little
- Search for existing content before adding anything new
- Make the smallest reasonable changes

## Hard constraints

- Never use --no-verify when committing
- Test all links before publishing
- No untested code examples

## See also

- Style rules: enforced by Vale (.vale.ini)
- Git workflow: enforced by hooks (.claude/settings.json)
- Workflow commands: see .claude/skills/

Extend Claude's capabilities

Once you've got a CLAUDE.md, move the mechanical rules somewhere that enforces them reliably without relying on Claude to remember them. Then layer in tools that give Claude persistent context and reusable workflows.

Enforce rules with hooks and linters

Hooks are shell commands that run automatically at specific points in Claude's workflow—before or after a tool call, or at the end of a session. They're configured in .claude/settings.json and give you deterministic enforcement instead of hoping Claude follows an instruction.

For documentation teams, two hooks are often useful:

• Style linting with Vale: Vale is a prose linter that enforces style rules for tone, terminology, and formatting. Run it automatically whenever Claude writes or edits a file to catch style violations before they reach a commit.
• Blocking risky git commands: A PreToolUse hook can intercept any bash command and block it if it matches a pattern—like --no-verify.

Here's a .claude/settings.json example that does both:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "vale \"$(jq -r '.tool_input.file_path // empty')\""
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "if jq -r '.tool_input.command' | grep -q -- '--no-verify'; then echo 'Blocked: --no-verify is not permitted'; exit 2; fi"
          }
        ]
      }
    ]
  }
}

Help Claude make memories

Claude Code has a built-in memory system to persist context across sessions. It's on by default. As you work, Claude automatically saves things worth remembering to a memory directory specific to your project.

The memory directory lives outside the repo at ~/.claude/projects/<project>/memory/ and contains a MEMORY.md index loaded at the start of every session.

Claude decides what's worth saving on its own, but you can also ask it directly to write a memory. "Remember that I don't want emoji in docs" or "save this decision to memory." Use /memory in any session to browse, edit, or delete memories.

Build repeatable workflows with skills

Claude Code supports custom slash commands, which are project-specific workflows you invoke with a /skill-name shorthand. If you find yourself giving Claude the same set of instructions repeatedly, that's a good candidate for a skill.

For example, I have a lot of workflows running in our docs repo to test the feature and find edge cases. This results in dozens of pull requests created by bots every day. I have a skill that audits all open pull requests authored by a bot; identifies duplicates or invalid PRs and closes them; and tags me to review the remaining ones. What used to be a manual, time consuming review process is now a single command.

To create a skill, add a directory to .claude/skills/ containing a SKILL.md file with instructions describing what the skill does. Any time you type /skill-name, Claude uses the skill's instructions to perform the task.

.claude/skills/
└── my-skill/
    └── SKILL.md

Anthropic also hosts official plugins to add skills at https://claude.com/plugins/. Install the Mintlify plugin to give Claude Code best practices for updating your docs with Mintlify components.

Organize your workspace

If you're working across multiple related repositories (like docs/, backend/, and frontend/), organize them under a common parent directory. This allows Claude Code to efficiently search between projects and better assess the relationships between code and documentation.

parent-dir/
├── docs/
├── backend/
└── frontend/

Three helpful AI documentation workflows

Sharing these with my team is how I'm planning to take time off without worrying about our docs.

Documenting new features

Instead of starting from a blank page, give Claude context about what changed and have it help identify how to document a new feature.

Here's my process:

1. Give Claude context: Either describe what changed or point Claude to the Git branch with the changes. Claude can examine a Git diff and describe what is being changed. I find this especially helpful when I need to quickly understand the changes on a branch.
2. Verify understanding: Have Claude explain back what it thinks changed before you continue.
3. Get a plan: Ask Claude to look at existing docs and propose how to update them, or if there should be new pages.
4. Work in chunks: Make changes in small, reviewable iterations.

Sample prompt:

I need to document a new feature. Please:
1. Analyze the code changes in this branch: feature/cool-new-thing
2. Search through docs/ to see if any existing pages need updates
3. Identify what pages need to be updated and if new documentation is needed
4. Suggest the best location for new content (prefer updating existing pages)
5. Show me your plan for making these content updates

Finding and updating existing docs

This workflow is great for maintenance. Claude Code is good at finding related content scattered across multiple pages.

I'll ask Claude to:

1. Search for related pages: "Search the docs/ directory for pages related to [topic]"
2. Review before changing anything: "Read [file-path] and suggest improvements for [specific issue]"
3. Make targeted updates: "Update [file-path] to [specific change]. Keep the existing style."

Quality review

For a first review, Claude can do a nice job catching grammar, spelling, formatting, and style errors. It's not as good as humans at seeing the strategy behind content and confirming that docs will meet users' needs, but with some specific prompting it can help you evaluate your content.

Sample prompt:

Please review the changes I'm about to commit and check:
1. Do they follow our writing standards?
2. Do they follow general technical writing best practices?
3. Are code examples accurate?
4. Is the frontmatter complete and correct?
5. Are there any links that need testing?
6. Do the docs make sense? Would a user be successful following them?

Final tips on using Claude Code for writing documentation

Don't

1. Don't treat CLAUDE.md like a configuration dump. The instinct when starting out is to add every rule you can think of. Resist it. A long instruction file becomes noise. Start lean and add more if you need it.
2. Don't trust Claude's technical knowledge. Claude can write very convincing explanations for APIs that don't exist. Always verify technical claims against the actual code and your testing.
3. Don't skip planning. The planning step is important for you and for Claude. It gives you a chance to confirm what the tool is going to do and it helps Claude Code work more efficiently by getting you to verify what it's going to attempt before it does it. Don't jump straight into asking it to write documentation. It'll probably get messy.

Do

1. Always get human review. No matter how good Claude's output looks, have another person review it. This catches technical errors and ensures it actually makes sense to someone who didn't write it.
2. Start small. Big documentation rewrites usually fail. Work on one section at a time, test each code example, verify each link.
3. Move mechanical rules out of CLAUDE.md. If a rule can be enforced by something deterministic like a linter or a hook, it should be.

The bottom line

I'm not trying to replace human expertise with AI. I have no doubt that I will be gladly welcomed back from vacation, not replaced by Claude while I'm away. Claude Code can help expedite some mechanical aspects of writing like searching; it can help plan content updates; and it can generate content. But all of this requires human oversight.

The teams I've talked to who are successfully using these tools aren't just trying to write faster, they're trying to be more thoughtful and identify how their content addresses user needs rather than just trying to keep up with the pace of releases.

For non writers who are creating documentation, tools like Claude Code can give you confidence and get over that initial hurdle of "but I'm not a writer." Even before LLMs took off, I've always believed anyone can write. It's hard and can be intimidating, but it's achievable. Claude Code and similar tools are one way to get there.

At least until your writer is back.

-

What's your experience with AI tools for technical writing? What workflows have you found most effective? I'm always curious to hear how other teams are approaching novel technology - feel free to drop me a note any time!