Why We Document Everything as Blog Posts (And You Should Too)

Today we cleaned up our repository by converting 29 root-level markdown documentation files into comprehensive blog posts. But this wasn't just about tidiness - it was about fundamentally rethinking how we approach documentation.

The Problem with Traditional Documentation

Most projects have documentation scattered across multiple locations:

• README.md - Basic setup
• CONTRIBUTING.md - Contribution guidelines
• docs/ folder - Feature docs
• CHANGELOG.md - Version history
• Various *_FIX.md files - Bug fixes and patches
• Wiki pages - User guides
• Issue comments - Implementation details

This creates several problems:

1. Documentation Rot

Internal docs get outdated quickly because they're not visible to users. No one reads them, so no one updates them.

2. Zero SEO Value

Markdown files in your repository aren't indexed by Google. Users can't find solutions to their problems through search.

3. Duplicate Content

The same feature gets documented in multiple places (code comments, docs folder, wiki, blog). They inevitably diverge.

4. Poor Discoverability

Contributors can't find relevant docs because they're scattered across different systems with different search mechanisms.

5. No Traffic Generation

Internal documentation doesn't drive visitors to your project. It's purely maintenance overhead with no marketing benefit.

Our Solution: Blog-First Documentation

We established a simple rule:

All feature documentation must be blog posts in content/posts/. No exceptions.

The only markdown files allowed in our root directory are:

1. README.md - Project setup and quick start
2. AGENTS.md - Core knowledge base for AI coding agents

Everything else goes in content/posts/ as a blog post.

What We Cleaned Up

We had accumulated 29 documentation files in our root directory:

Scanner Documentation (11 files)

• SCANNER_SNAP_FIX.md
• SCANNER_PRICING_FEATURE.md
• SCANNER_HYBRID_RANKING_FIX.md
• SCANNER_DEBUG_IMPROVEMENTS.md
• EMERALD_DRAGON_FIX.md
• And 6 more...

SEO Documentation (5 files)

• SEO_IMPROVEMENTS.md
• CARD_SEO_FIX.md
• NLWEB_SEO_ALIGNMENT.md
• And 2 more...

Feature Documentation (8 files)

• WHY_BUTTON_FIX.md
• DECK_STUDIO_SIMPLIFIED.md
• ART_SPECIFIC_SHARING.md
• And 5 more...

Build/Deployment Documentation (5 files)

• LINUX_BUILD_FIX.md
• BUILD_SUCCESS.md
• DEPLOYMENT_SUMMARY.txt
• And 2 more...

All of these contained valuable information, but nobody could find them and Google wasn't indexing them.

The Transformation Process

We converted these 29 files into 5 comprehensive blog posts:

1. Deck Studio Simplification

From: DECK_STUDIO_SIMPLIFIED.md
To: content/posts/deck-studio-simplification.md
Focus: KISS approach, removing AI complexity, lessons learned

2. Emerald Dragon Scanner Fix

From: EMERALD_DRAGON_FIX.md
To: content/posts/emerald-dragon-scanner-fix.md
Focus: Multi-word card extraction, OCR improvements, type line filtering

3. Scanner Hybrid Ranking Fix

From: SCANNER_HYBRID_RANKING_FIX.md
To: content/posts/scanner-hybrid-ranking-fix.md
Focus: Art-confirmed matches, algorithm design, user experience

4. Art-Specific Social Sharing

From: ART_SPECIFIC_SHARING.md, SOCIAL_PREVIEW_FIX.md, ART_SPECIFIC_IMAGE_PATH_FIX.md
To: content/posts/art-specific-social-sharing.md
Focus: Query parameters, metadata generation, social media previews

5. Rethinking Card Page SEO

From: CARD_SEO_FIX.md, SEO_IMPROVEMENTS.md, SEO_CHANGES_README.md
To: content/posts/rethinking-card-page-seo.md
Focus: User intent, search optimization, metadata simplification

Each blog post synthesizes multiple documentation files, adds context and storytelling, and explains both the "what" and the "why."

The Blog-First Workflow

We established a mandatory process for all future documentation:

Step 1: Check Existing Posts

Before creating any documentation, search content/posts/ for relevant blog posts:

# Search for posts about the scanner
ls content/posts/ | grep -i scanner

# Results:
# mtg-card-scanner-hybrid-search-pricing.md
# emerald-dragon-scanner-fix.md
# scanner-hybrid-ranking-fix.md

Step 2: Update or Create

• If relevant post exists: Update it with new sections
• If no relevant post exists: Create a new blog post

Step 3: Never Create Root .md Files

The only exceptions are README.md and AGENTS.md. Everything else is a blog post.

Example: Scanner Pricing Feature

❌ Wrong Approach:

1. Add pricing to scanner
2. Create SCANNER_PRICING.md in root
3. Document implementation details  
4. Commit and forget

✅ Correct Approach:

1. Add pricing to scanner
2. Check if content/posts/mtg-card-scanner-*.md exists
3. Found: mtg-card-scanner-hybrid-search-pricing.md
4. Add new section: "Pricing Display Feature"
5. Include code examples and user benefits
6. Update frontmatter date to today
7. Commit updated blog post

The blog post now documents all scanner features in one place, it's SEO-indexed, and users can find it via Google.

Why Blog Posts Win

1. SEO Benefits

Before (internal docs):

• Not indexed by Google
• No organic traffic
• Zero backlink potential
• Hidden from search engines

After (blog posts):

• Indexed by Google within days
• Target specific keywords naturally
• Generate organic traffic
• Build domain authority through links

Our scanner blog post now ranks for:

• "MTG card scanner"
• "OCR Magic card recognition"
• "identify Magic cards with camera"
• "hybrid search card scanner"

2. Discoverability

Before: "Where's the doc on the scanner fix?"
Developer checks: README? docs/ folder? Wiki? GitHub issues? Gives up.

After: "How does the scanner work?"
User searches: "takescake card scanner" → Blog post appears → Full documentation

3. Single Source of Truth

Instead of:

• Code comments explaining the algorithm
• SCANNER_FIX.md in root explaining the bug
• GitHub issue explaining the solution
• Wiki page explaining usage

We have:

• One comprehensive blog post with everything
• Code references the blog post URL
• GitHub issues reference the blog post URL
• Users, contributors, and AI agents all read the same post

4. Natural Updates

Blog posts get updated because people read them:

• Users comment with questions → We add FAQs
• Contributors reference them → We keep them current
• Search traffic highlights gaps → We fill them

Internal docs rot because nobody reads them.

5. Marketing Value

Every documentation blog post is also a marketing opportunity:

• Discovery: Users find our site via documentation searches
• Trust: Comprehensive docs signal quality and reliability
• Community: Detailed technical posts attract technical users
• Authority: Good documentation positions us as experts
• Sharing: Users share helpful blog posts on social media

Internal docs provide zero marketing value.

What Makes a Good Documentation Blog Post

Based on our conversion work, here's what works:

1. Start with the Problem

Don't lead with implementation. Start with what was broken or why we built the feature.

Bad: "We implemented a hybrid ranking algorithm using..."
Good: "Users were scanning Snap but getting Snapback as the top result..."

2. Include Real Examples

Show actual before/after outputs, screenshots, or debug logs.

Before:
  1. Snapback - 85%
  2. Snap - 78%

After:
  1. Snap - 98%
  2. Snapback - 75%

Real data makes abstract concepts concrete.

3. Explain Trade-offs

Don't just document what you did - explain why and what you rejected.

"We considered using a pre-trained ML model but chose art similarity because:

1. No external dependencies
2. Works offline
3. Predictable performance
4. Easy to debug"

4. Add Context and Storytelling

Turn dry technical details into a narrative with characters (developers, users), conflict (bugs, requirements), and resolution (the fix).

5. Include Code But Don't Overwhelm

Show key snippets that illustrate the approach, but link to full source code. Don't paste entire files.

6. Write for Multiple Audiences

• Skimmers: Clear headings, bullet points, before/after comparisons
• Users: How-to sections, examples, "Try it yourself"
• Developers: Implementation details, code snippets, architecture decisions
• AI Agents: Structured information, clear problem/solution format

7. End with Lessons Learned

What would you do differently? What surprised you? What did you learn?

"We thought ML would be essential, but simple art similarity worked better because..."

8. SEO Without Keyword Stuffing

Use natural language that includes relevant terms:

• Feature names ("card scanner", "hybrid ranking")
• Problem descriptions ("OCR not matching card names")
• Solution approaches ("art similarity algorithm")

Don't force keywords. Write naturally and SEO follows.

The Results

Repository Cleanup

Before: 29 markdown files cluttering root directory
After: Only README.md and AGENTS.md in root, everything else in content/posts/

Documentation Quality

Before: Scattered, inconsistent, incomplete
After: Comprehensive blog posts with examples, context, and lessons learned

SEO Potential

Before: Zero - internal docs aren't indexed
After: Every post targets specific keywords and drives organic traffic

Maintainability

Before: Docs rot because nobody reads them
After: Blog posts get updated because users find and reference them

User Experience

Before: Users can't find answers to common questions
After: Users Google their question → Find our blog post → Get complete answer

Implementing Blog-First Documentation

Want to adopt this approach? Here's how:

1. Audit Your Documentation

List all documentation locations:

# Find all markdown files
find . -name "*.md" -not -path "./node_modules/*"

# Find docs folders
find . -type d -name "docs" -o -name "documentation"

# Check wiki pages
# Check GitHub issue templates
# Check code comments with TODOs

2. Identify Consolidation Opportunities

Group related documentation:

• Scanner-related fixes → One comprehensive scanner post
• SEO improvements → One SEO strategy post
• API changes → One API guide post

3. Create Your First Documentation Blog Post

Pick your most-asked question and write a comprehensive blog post answering it:

• Include the problem users face
• Show the solution step-by-step
• Add code examples and screenshots
• Link to relevant API docs or source code
• End with troubleshooting tips

4. Establish the Blog-First Policy

Update your CONTRIBUTING.md:

## Documentation Policy

All feature documentation must be blog posts:

1. Check if a relevant post exists in `content/posts/`
2. If yes, update that post with new information
3. If no, create a new blog post (not a markdown file in root)

Exceptions: README.md and CONTRIBUTING.md only.

5. Convert Gradually

Don't try to convert everything at once. Each time you touch a feature:

1. Check if there's old documentation
2. Convert it to a blog post
3. Delete the old docs
4. Update links to point to the blog post

Over time, your documentation migrates to blog posts naturally.

6. Make It Easy to Update

Use proper frontmatter so posts are easy to update:

---
title: "Feature Name: Complete Guide"
date: "2025-10-06"  
updated: "2025-10-15"  # Track updates
excerpt: "One-line summary"
tags: ["feature-name", "guide"]
---

When you update a post, bump the updated date.

Common Objections

"Blog posts feel too informal for technical docs"

Blog posts can be as technical as you want. The format doesn't determine the depth - you do.

Our blog posts include:

• Algorithm explanations
• Code snippets with line-by-line analysis
• Performance benchmarks
• Architecture diagrams
• Trade-off discussions

They're comprehensive technical documents that happen to be public and indexed.

"What about internal-only information?"

Some things genuinely need to stay internal (API keys, infrastructure details, security notes). For those:

• Keep them in a private wiki or internal docs system
• Reference them from blog posts: "See internal docs for deployment details"
• Make the internal docs minimal - just what must stay private

But question whether something really needs to be internal. Most implementation details can be public.

"Blog posts get outdated too"

True! But they're more likely to be updated than internal docs because:

1. Users find them and report issues
2. Search traffic shows what needs updating
3. They're visible, so teams notice when they're stale
4. Updating them improves SEO, creating incentive

Internal docs rot silently. Blog posts rot visibly, which prompts updates.

"This creates duplicate documentation"

Only if you keep the old docs! The key is:

1. Convert old docs to blog posts
2. Delete the old docs
3. Update all links to point to blog posts
4. From now on, only update the blog posts

Single source of truth in blog format.

"What about API reference docs?"

API reference docs (auto-generated from code) are different from feature documentation:

• Reference docs: Auto-generated, comprehensive, dry
• Blog posts: Hand-written, contextual, storytelling

Use both:

• Generate API references automatically (Swagger, JSDoc, etc.)
• Write blog posts explaining how to use the APIs

Example:

• API reference: "POST /api/cards/scan - Params: image (base64), debug (boolean)"
• Blog post: "How to Use the Card Scanner API" - Includes example code, common pitfalls, troubleshooting

The Long-Term Vision

Documentation as blog posts creates a flywheel:

1. Write blog post documenting a feature
2. Users find it via Google search
3. They visit your site, try the feature
4. They share the post if it helped them
5. More users find you via shared links
6. SEO improves from traffic and backlinks
7. More users find you via organic search
8. Repeat with next feature

Traditional internal documentation has no flywheel - it's pure maintenance cost.

Try It Yourself

Pick one markdown file in your repository that isn't README or CONTRIBUTING. Convert it to a blog post:

1. Add frontmatter (title, date, excerpt, tags)
2. Write an introduction explaining the problem
3. Keep the technical details but add context
4. Include examples that illustrate key points
5. End with lessons learned or next steps
6. Publish it publicly
7. Delete the old markdown file
8. Update links to point to the new blog post

See how it feels. We bet you'll like the result better than the original doc.

Conclusion

Documentation doesn't have to be a chore hidden in your repository. By documenting features as blog posts, you:

• ✅ Drive SEO and organic traffic
• ✅ Help users discover your project
• ✅ Create a single source of truth
• ✅ Build domain authority
• ✅ Make documentation visible (reducing rot)
• ✅ Turn maintenance cost into marketing value

We converted 29 scattered markdown files into 5 comprehensive blog posts. Our repository is cleaner, our documentation is better, and now Google can help users find our features.

Your documentation should work for you, not against you. Make it a blog post.

---

See the results: Browse our blog posts to see how we document scanner fixes, SEO improvements, and architectural decisions as public, searchable content.

Read the policy: Check AGENTS.md to see our complete blog-first documentation policy.