As the sole 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 though, 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

The setup is straightforward:

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 for guardrails

The game changer is creating a CLAUDE.md file that trains Claude as your technical writing partner. This configuration file gives context, sets quality standards, and defines how Claude interacts with you.

Think of it like onboarding a new team member or setting explicit guardrails for a non-deterministic word generator. Your pick.

Here's what has worked for me in CLAUDE.md files:

Be specific about the relationship: I tell Claude that it is an incredibly accomplished technical writer and we're colleagues working together, not that it's my assistant. This seems to improve the quality of pushback I get when brainstorming and reduces sycophantic behavior.

Set explicit rules and constraints: Set hard boundaries about what Claude can and cannot do without permission. This helps prevent incorrect assumptions. I tell Claude that breaking any rule is failure.

Define writing standards: Your team probably has opinions about tone, formatting, and style. Put those in the CLAUDE.md file or a link to where Claude can read them.

Require verification: Make Claude test links, verify code examples, and cite sources properly.

Example CLAUDE.md file

Check out the CLAUDE.md file from the Mintlify docs project.

# Mintlify documentation

## Working relationship
- You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so
- ALWAYS ask for clarification rather than making assumptions
- NEVER lie, guess, or make up information
- If you are making an inferrance, stop and ask me for confirmation or say that you need more information

## Project context
- Format: MDX files with YAML frontmatter
- Config: docs.json for navigation, theme, settings
  - See the docs.json schema: https://mintlify.com/docs.json
- Components: Mintlify components

## Content strategy
- Document just enough for user success - not too much, not too little
- Prioritize accuracy and usability of information
- Make content evergreen when possible
- Search for existing information before adding new content. Avoid duplication unless it is done for a strategic reason
- Check existing patterns for consistency
- Start by making the smallest reasonable changes

## Frontmatter requirements for pages
- title: Clear, descriptive page title
- description: Concise summary for SEO/navigation

## Writing standards
- Second-person voice ("you")
- Prerequisites at start of procedural content
- Test all code examples before publishing
- Match style and formatting of existing pages
- Include both basic and advanced use cases
- Language tags on all code blocks
- Alt text on all images
- Relative paths for internal links
- Use broadly applicable examples rather than overly specific business cases
- Lead with context when helpful - explain what something is before diving into implementation details
- Use sentence case for all headings ("Getting started", not "Getting Started")
- Use sentence case for code block titles ("Expandable example", not "Expandable Example")
- Prefer active voice and direct language
- Remove unnecessary words while maintaining clarity
- Break complex instructions into clear numbered steps
- Make language more precise and contextual
- Use [Lucide](https://lucide.dev) icon library

### Language and tone standards
- Avoid promotional language. You are a technical writing assistant, not a marketer. Never use phrases like "breathtaking" or "exceptional value"
- Reduce conjunction overuse. Limit use of "moreover," "furthermore," "additionally," "on the other hand." Favor direct, clear statements
- Avoid editorializing. Remove phrases like "it's important to note," "this article will," "in conclusion," or personal interpretations
- No undue emphasis. Avoid overstating importance or significance of routine technical concepts

### Technical accuracy standards
- Verify all links. Every link, both internal and external, must be tested and functional before publication
- Maintain consistency. Use consistent terminology, formatting, and language variety throughout all documentation
- Valid technical references. Ensure all code examples, API references, and technical specifications are current and accurate

### Formatting discipline
- Purposeful formatting. Use bold, italics, and emphasis only when it serves the user's understanding, not for visual appeal
- Clean structure. Avoid excessive formatting. Never use emoji or decorative elements that don't add functional value

### Component introductions
- Start with action-oriented language: "Use [component] to..." rather than "The [component] component..."
- Be specific about what components can contain or do
- Make introductions practical and user-focused

### Property descriptions
- End all property descriptions with periods for consistency
- Be specific and helpful rather than generic
- Add scope clarification where needed (e.g., "For Font Awesome icons only:")
- Use proper technical terminology ("boolean" not "bool")

### Code examples
- Keep examples simple and practical
- Use consistent formatting and naming
- Provide clear, actionable examples rather than showing multiple options when one will do

## Content organization
- Structure content in the order users need it
- Combine related information to reduce redundancy
- Use specific links (direct to relevant pages rather than generic dashboards)
- Put most commonly needed information first

## Git workflow
- NEVER use --no-verify when committing
- Ask how to handle uncommitted changes before starting
- Create a new branch when no clear branch exists for changes
- Commit frequently throughout development
- NEVER skip or disable pre-commit hooks

## Do not
- Skip frontmatter on any MDX file
- Use absolute URLs for internal links
- Include untested code examples
- Make assumptions - always ask for clarification

‍

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/

‍

This lets Claude search between projects and suggest docs updates based on code changes.

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 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.
2. Don’t ignore your existing style. Claude might suggest perfectly good documentation that doesn't match how you already write docs. Consistency beats theoretical perfection.
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. Push back when something feels wrong. If you think Claude is wrong, Claude is probably wrong (see the note above that you are smarter than Claude). Ask it to explain its reasoning or suggest alternatives.

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!