Tutorial Library Generator

An automated documentation factory for creating, reviewing, and translating beginner-focused technical tutorials using Claude Code slash commands.

Overview

This system automates the complete tutorial lifecycle:

• Research current, accurate information
• Generate structured, beginner-friendly content
• Review against 30+ quality criteria
• Translate to multiple languages while preserving technical accuracy
• Maintain consistency across all tutorials

Features

• 5 Specialized Slash Commands - Automate every stage of tutorial creation
• Consistent Quality - 30+ criteria across 5 categories ensure every tutorial meets high standards
• Multilingual Support - Built-in translation commands for Chinese, Spanish, and easy extensibility
• Beginner-Focused - Every tutorial designed for complete beginners
• Rapid Production - Generate comprehensive tutorials in minutes instead of hours

Quick Start

1. Create a New Tutorial

/tutorial

Provide a topic, and the system will:

1. Research current information via web search
2. Create a structured plan for your approval
3. Generate a complete tutorial following best practices
4. Save to tutorials/en/[topic-name].md

2. Review Tutorial Quality

/review-tutorial

Provide the file path, and get a comprehensive quality report checking:

• Content accuracy
• Formatting standards
• Beginner accessibility
• Technical accuracy
• Writing quality

3. Translate to Other Languages

/translate-chinese

or

/translate-spanish

Provide the English file path to create a high-quality translation that:

• Preserves all code and technical terms
• Translates instructional content
• Follows language-specific conventions
• Maintains natural phrasing

4. Verify Translation Quality

/review-translation

Provide both the English original and translation to check:

• Content synchronization
• Code preservation
• Language quality
• Technical accuracy

Repository Structure

.
├── .claude/
│   └── commands/           # Slash command definitions
│       ├── tutorial.md
│       ├── review-tutorial.md
│       ├── translate-chinese.md
│       ├── translate-spanish.md
│       └── review-translation.md
├── tutorials/
│   ├── en/                 # English tutorials
│   ├── zh/                 # Chinese (简体中文)
│   ├── es/                 # Spanish (Español)
│   ├── fr/                 # French (Français)
│   ├── de/                 # German (Deutsch)
│   └── ja/                 # Japanese (日本語)
├── templates/
│   └── tutorial-template.md  # Tutorial structure reference
├── docs/
│   └── quality-criteria.md   # Complete quality standards
└── README.md               # This file

Slash Commands Reference

/tutorial - Generate New Tutorial

Purpose: Create a comprehensive, beginner-friendly tutorial on any topic

Process:

1. Web research for current information
2. Planning with user approval
3. Structured writing following template
4. Testing and verification
5. Quality self-check
6. Save to tutorials/en/

Output: Complete tutorial ready for review

---

/review-tutorial - Quality Assurance

Purpose: Comprehensive quality check against 30+ criteria

Input: Path to tutorial file

Checks:

• Content Accuracy - Technical correctness, working code, valid links
• Formatting Standards - Markdown, structure, consistency
• Beginner Accessibility - Clear explanations, no jargon, encouraging tone
• Technical Accuracy - Valid syntax, security, best practices
• Writing Quality - Grammar, flow, clarity

Output: Detailed review report with severity ratings and recommendations

---

/translate-chinese - Chinese Translation

Purpose: Translate tutorial to Simplified Chinese (简体中文)

Input: Path to English tutorial

Process:

1. Read and understand source
2. Translate while preserving code
3. Polish for natural Chinese
4. Quality check
5. Save to tutorials/zh/

Preserves: Code, commands, URLs, technical terms, file paths

Translates: Instructions, explanations, headings, descriptions

Output: Natural Chinese translation maintaining technical accuracy

---

/translate-spanish - Spanish Translation

Purpose: Translate tutorial to Spanish (Español)

Input: Path to English tutorial

Process:

1. Read and understand source
2. Translate using tú form
3. Polish for natural Spanish
4. Quality check
5. Save to tutorials/es/

Preserves: Code, commands, URLs, technical terms, file paths

Translates: Instructions, explanations, headings, descriptions

Style: Informal tú form, inverted punctuation (¿? ¡!), neutral Latin American Spanish

Output: Natural Spanish translation maintaining technical accuracy

---

/review-translation - Translation Verification

Purpose: Verify translation matches original and follows language guidelines

Input: Paths to both English original and translation

Checks:

• Content synchronization (no missing/extra sections)
• Code preservation (all code unchanged)
• Language-specific quality (punctuation, tone, grammar)
• Formatting consistency
• Translation quality (natural phrasing)
• Technical accuracy

Output: Detailed comparison report with issues and recommendations

Tutorial Structure

Every tutorial follows this structure:

[← Back to Tutorial Library](../README.md)

# Title
[Engaging 2-3 sentence hook]

## What You'll Learn
[Clear objectives]

## Prerequisites
[Required knowledge and tools]

## Understanding the Concepts
[Fundamental explanations]

## Step-by-Step Instructions
[Numbered, actionable steps with code examples]

## Troubleshooting
[At least 3 common problems with solutions]

## Next Steps
[At least 2 suggestions for further learning]

## Additional Resources
[Links to official docs and helpful resources]

See templates/tutorial-template.md for complete template.

Quality Standards

All tutorials must meet these standards:

Content

• ✅ Technically accurate and current
• ✅ All code tested and working
• ✅ Valid links and references
• ✅ Complete prerequisites and steps

Format

• ✅ Home link at top
• ✅ One H1, proper heading hierarchy
• ✅ Code blocks with language tags
• ✅ Consistent formatting
• ✅ Kebab-case filenames

Beginner Focus

• ✅ Engaging hook
• ✅ No unexplained jargon
• ✅ Small, clear steps
• ✅ Encouraging tone
• ✅ Explicit prerequisites

Technical Quality

• ✅ Valid syntax
• ✅ Secure code (no vulnerabilities)
• ✅ Best practices
• ✅ Error handling where needed

Writing

• ✅ Clear and concise
• ✅ Correct grammar and spelling
• ✅ Logical flow
• ✅ Active voice

See docs/quality-criteria.md for complete criteria (30+ items).

Workflow Examples

Example 1: Create and Publish Tutorial

1. /tutorial
   → "I want to create a tutorial on Docker basics"
   → Reviews plan, generates tutorial
   → Saves to tutorials/en/docker-basics.md

2. /review-tutorial
   → Provides path: tutorials/en/docker-basics.md
   → Gets quality report, makes fixes

3. /translate-chinese
   → Provides path: tutorials/en/docker-basics.md
   → Saves to tutorials/zh/docker-basics.md

4. /review-translation
   → Provides both paths
   → Verifies quality, makes any needed fixes

5. Repeat translation for other languages

Example 2: Update Existing Tutorial

1. Make changes to tutorials/en/existing-tutorial.md

2. /review-tutorial
   → Verify changes meet quality standards

3. /review-translation tutorials/en/existing-tutorial.md tutorials/zh/existing-tutorial.md
   → Check if translations need updating

4. If needed, /translate-chinese to regenerate translation

Translation Guidelines

What to Preserve

Always keep in English:

• All code blocks
• Commands and file paths
• URLs and links
• Technical terms (API, function, variable, etc.)
• Brand names (GitHub, React, Python, etc.)
• Inline code elements (npm install, variable_name)
• Environment variables

What to Translate

Translate to target language:

• All instructional text
• Section headings
• Step descriptions
• Troubleshooting descriptions
• Conceptual explanations
• Next steps suggestions

Language-Specific Rules

Chinese (简体中文):

• Use Chinese punctuation (。，！？)
• No spaces between Chinese characters
• Spaces around English words in Chinese text
• Formal, educational tone (书面语)
• Natural phrasing (avoid literal translation)

Spanish (Español):

• Use tú form (informal)
• Inverted punctuation (¿? ¡!)
• Natural Spanish phrasing
• Neutral Latin American Spanish
• Proper articles with technical terms (el API, la función)

Extending the System

Adding New Language

1. Create translation command:

   .claude/commands/translate-[language].md
   

2. Define language-specific rules:

   • What punctuation to use
   • Formality level (formal/informal)
   • Technical term handling
   • Common translations

3. Create directory:

   mkdir tutorials/[language-code]
   

4. Test with existing tutorial

5. Update this README

Creating Custom Commands

Add new .md files to .claude/commands/ following this pattern:

# Command Name

Brief description

## Usage
[How to use]

## Process
[Step-by-step what the command does]

## Output
[What the user gets]

Best Practices

For Tutorial Creation

1. Research thoroughly before writing
2. Test all code examples
3. Put yourself in beginner's shoes
4. Be encouraging, never condescending
5. Explain "why" not just "how"

For Reviews

1. Check all 5 categories systematically
2. Provide specific, actionable feedback
3. Include line numbers for issues
4. Prioritize critical issues first
5. Note strengths, not just problems

For Translations

1. Read entire source first for context
2. Preserve ALL code exactly
3. Translate for native speaker fluency
4. Check language-specific conventions
5. Verify synchronization with original

Statistics

This system can help you:

• Generate comprehensive tutorials in 15-20 minutes (vs 2-3 hours manually)
• Review against 30+ criteria in 5 minutes (vs 20-30 minutes manually)
• Translate tutorials in 10 minutes (vs 30-60 minutes manually)
• Maintain consistent quality across unlimited tutorials
• Scale to multiple languages effortlessly

Philosophy

"Start manual, then automate"

This system codifies the workflows refined through hands-on tutorial creation. Each command represents:

• Experience - Learned through creating tutorials manually
• Standards - Discovered through iteration and feedback
• Efficiency - Automated repetitive quality checks
• Consistency - Enforced patterns across all content

Contributing

Adding Tutorials

Use /tutorial to maintain consistency with existing content.

Improving Commands

Commands are defined in .claude/commands/. To improve:

1. Edit the relevant .md file
2. Test with existing tutorials
3. Document changes in this README

Reporting Issues

If you find issues with:

• Generated tutorials - Use /review-tutorial to identify problems
• Translations - Use /review-translation to verify quality
• Commands - Review and update command .md files

Troubleshooting

Issue: Tutorial doesn't follow template

Solution: Use /review-tutorial to identify missing sections, then update tutorial to match templates/tutorial-template.md

Issue: Translation contains English text

Solution: Use /review-translation to find untranslated sections. Re-translate those sections while preserving code elements.

Issue: Code not working

Solution: Run /review-tutorial focusing on "Technical Accuracy" category. Test all code examples in appropriate environment.

Issue: Inconsistent quality across tutorials

Solution: Run /review-tutorial on all tutorials and fix issues. Use docs/quality-criteria.md as reference.

Resources

• Tutorial Template: templates/tutorial-template.md
• Quality Criteria: docs/quality-criteria.md (complete 30+ item checklist)
• Slash Commands: .claude/commands/ (all command definitions)
• Example Output: Check tutorials/ for examples (when available)

License

[Specify your license]

Acknowledgments

Built with Claude Code and inspired by the need for consistent, high-quality beginner tutorials.

---

Ready to generate your first tutorial? Run /tutorial and provide a topic!