Three years ago, I started a project that made no sense: an open-source xianxia (Chinese fantasy) novel called Compiling the Dao. The premise was absurd—what if cultivation was literally programming? What if qi was just energy management? What if tribulations were basically deployment failures?
I thought it would be fun. I didn't expect it to teach me more about software architecture than most technical blogs.
The Stack Behind the Story
Before we dive in, let me explain what Compiling the Dao actually is:
- Concept: A xianxia novel where cultivation follows programming principles
- Metaphor System: Qi = Memory, Meridians = Network, Tribulations = Compilation errors
- Platform: Open-source, community-contributed chapters
- Repository: Compiling the Dao
What started as a joke became a 847-day experiment in maintaining a creative codebase with contributors across time zones. And the lessons? They map surprisingly well to actual software development.
Lesson 1: Metaphor Consistency Is Your Type System
When I started writing, I made every creative writer's mistake: I improvised the magic system.
Chapter 1: Qi is like electricity.
Chapter 5: Actually, qi is more like object-oriented programming.
Chapter 12: Qi is basically async/await with callbacks.
By Chapter 20, readers were confused. "Wait, can qi be garbage collected? Or is it manually managed? You said meridians are networks, but now they're databases?"
This is exactly what happens when you build software without a type system. You introduce inconsistencies, contradictions, and edge cases that break everything.
The Fix: I created a dao-spec.md file—essentially a type definition for the cultivation system:
## Core Types
- **Qi**: Energy resource. Managed automatically by the Dao runtime.
- **Meridians**: Network channels. Support bidirectional flow.
- **Soul**: Persistent storage. Survives death (process restart).
- **Tribulation**: External validation. Required for major upgrades.
## Rules
1. Qi cannot be created, only transformed (conservation law)
2. Meridians have bandwidth limits (doS protection)
3. Soul backups require external artifacts (persistence guarantees)
Every chapter now references this spec. Before publishing, I run a "consistency check"—essentially a type checker for plot elements. Does this scene violate any rules? Does the metaphor still hold?
Software parallel: This is why we have schemas, interfaces, and contracts. Improvisation is fun until you have users.
Lesson 2: The Documentation Paradox
Here's a pattern I noticed around Day 300:
Contributors who read the docs: Submitted 3 chapters, 2 were rejected for inconsistency.
Contributors who didn't read the docs: Submitted 1 chapter, 1 was accepted.
Wait, what?
Turns out, documentation has a dark side. When you document too much, you create a barrier to entry. New contributors feel they need to understand everything before writing anything. They overthink. They write "correct" chapters that feel mechanical.
Meanwhile, the person who just jumped in wrote something fresh. Yes, it had inconsistencies—but those were easier to fix than the lifeless chapters from the "prepared" writers.
The Balance:
I split documentation into two tiers:
- Quick Start: 5-minute read, enough to write a chapter
- Deep Dive: For maintainers, not contributors
This mirrors good SDK design. You don't force users to read the entire API reference before "Hello World."
Software parallel: Over-documentation can be as harmful as under-documentation. Optimize for the happy path first.
Lesson 3: The Refactoring Trap
Around Day 500, I made a terrible mistake.
I decided to "refactor" the first 30 chapters. They were written early, before I had the metaphor system locked down. They were inconsistent. They used outdated terminology. They needed fixing.
Six weeks later, I had rewritten everything. The chapters were better. The metaphors were consistent. The prose was polished.
And I had written zero new chapters in six weeks.
Readers noticed. "Is this project dead?" "Why no updates?" The GitHub stars plateaued. The contributor mailing list went quiet.
I had optimized for technical perfection at the cost of momentum.
The Recovery:
I implemented a "forward-only" policy:
- New content takes priority over rewrites
- Refactoring is allowed only when it unblocks contributors
- Technical debt is tracked but not immediately addressed
This is essentially the "feature work > tech debt" prioritization that pragmatic teams use. Yes, clean code matters. But a dead project has perfectly clean code—because no one touches it.
Software parallel: Refactoring feels productive, but users don't see "improved internal consistency." They see "no new features."
Lesson 4: Open Source Governance Is Harder Than You Think
By Day 600, I had 15 contributors. Most were great. A few... weren't.
Problem 1: The Lore Expansionist
One contributor kept adding new cultivation realms, new magic systems, new factions. Every pull request expanded the universe. The story became bloated. I had to reject a 5,000-word chapter because it introduced a "Quantum Soul Realm" that broke everything.
Problem 2: The Tone Shifters
Another contributor wrote technically correct chapters... but in a completely different voice. My protagonist is introspective. Their version was an action hero. Both are valid styles, but mixing them jarred readers.
Problem 3: The Well-Meaning Fixer
A third contributor "fixed" inconsistencies—by changing old chapters to match their new ones. Suddenly, established scenes had different dialogue. Long-time readers were confused.
The Governance Layer:
I added a CONTRIBUTING.md with explicit guidelines:
- No new realms/magic systems without discussion
- Voice/style guide with examples
- Never modify existing chapters without explicit approval
I also created a "lore review" process. Every chapter is checked not just for consistency, but for scope creep and tone alignment.
Software parallel: This is code review at scale. You're not just checking for bugs—you're checking for architectural fit, style consistency, and scope control.
Lesson 5: The Abstraction Trap
Here's the most embarrassing thing I'll admit:
I wrote a "chapter generator."
Yes, really. I thought, "What if I could abstract the writing process? Define character arcs as data structures? Plot points as state machines?"
I spent two weeks building it. The system had:
- Character templates with relationship graphs
- Plot beat generators
- Conflict/resolution state machines
- A "prose renderer" that turned beats into paragraphs
The output was technically impressive. And absolutely unreadable.
It had no soul. No voice. No emotional resonance. It was the literary equivalent of code-generated HTML—structurally correct but aesthetically dead.
The Lesson:
Some things resist abstraction. Creativity is one of them. You can build tools to support the process, but you can't automate the core work.
This applies to software too. We've all seen the "framework that generates everything" projects. They produce impressive demos and terrible products. The hard problems—the ones that matter—require human judgment.
Software parallel: Not everything should be abstracted. Sometimes, writing "verbose" code (or prose) is the right approach.
The 847-Day Retrospective
If I had to summarize what this project taught me:
- Consistency systems matter—whether it's a type system or a metaphor system
- Documentation is a balance, not a panacea
- Momentum beats perfection—refactor responsibly
- Governance scales, chaos doesn't
- Some things can't be abstracted—embrace the craft
The project is still alive. Still evolving. Still teaching me things.
And if you're curious about a world where programmers cultivate the Dao, where bugs are demonic beasts, and where deployment failures are literal heavenly tribulations...
👉 Check out Compiling the Dao
Your Turn
Have you ever worked on a creative project that unexpectedly taught you engineering lessons? Or an engineering project that felt like creative writing?
I'm genuinely curious—what's your "Compiling the Dao" equivalent?
P.S. If you're wondering about the title: yes, it's a pun. Compiling the Dao. Getting the path to compile. I'm not sorry.
Top comments (0)