tomevault-io Format Design
"Smart people think of good things that are crazy enough that they just might work, and then they give them away, over and over, until they slowly take over the world." — Anil Dash
What Is It?
Format Design is the art of creating data formats, protocols, and conventions that actually get adopted. It's not about technical superiority — it's about fit, timing, and community.
Markdown beat Textile. JSON beat XML. RSS survived. Why?
The 10 Reasons Markdown Won
From Anil Dash's "How Markdown Took Over the World" (January 2025):
1. Had a Great Brand
"'Markdown' as a name is clever as hell. Get it — it's not markup, it's markdown."
- Memorable — Sticks in the mind
- Self-explanatory — Name implies purpose
- Clever — Rewards understanding
MOOLLM parallel: YAML Jazz, SOUL-CHAT, K-lines — memorable names that reward understanding.
2. Solved a Real Problem
"Millions of people were encountering the idea that it was too difficult or inconvenient to write out full HTML by hand."
Not abstract improvement. A specific, felt problem.
Test: Can you describe the pain point in one sentence? Can users?
3. Built on Existing Behaviors
"The format is based on the ways people had been adding emphasis and formatting to their text for years or even decades."
People already used *asterisks* for emphasis in email. Markdown just formalized it.
Principle: Don't invent new behaviors. Codify existing ones.
4. Mirrored RSS in Its Origin
"Both were spearheaded by a smart technologist who was also more than a little stubborn."
A champion who believed, advocated, and refined. Community built around a person.
Requirement: Someone must care deeply enough to keep pushing.
5. Community Ready to Help
"Markdown was part of a community that could build on it right from the start."
Prior art (Textile), beta testers (Aaron Swartz), early adopters (bloggers).
Principle: No format succeeds alone. Build with others.
6. Had the Right Flavor for Every Context
"Various communities that were implementing Markdown could add their own 'flavors' as they needed."
CommonMark for standardization. GitHub-Flavored for tables. Obsidian for wikilinks.
Principle: Core should be simple. Extensions should be possible.
7. Released at a Time of Behavior Change
"You can get people to change their behaviors when they're using a new tool."
Blogging was new in 2004. People were already learning new habits.
Timing matters: Launch during transitions (new platforms, new tools, new eras).
8. Came at the Cusp of the "Build Tool Era"
"Markdown is a raw material that has to be transformed into HTML, it perfectly fit this new workflow."
Build pipelines became standard. Markdown fit the compile-to-output model.
Principle: Align with emerging workflows, not legacy ones.
9. Worked with "View Source"
"It only takes one glimpse of a source Markdown file for anyone to understand how they might make a similar file of their own."
Inspectable. Learnable by example. No teaching required.
Test: Can someone learn your format by looking at one example?
10. Not Encumbered by IP
"There are no legal restrictions around Markdown. Nobody's been afraid to use the format."
No patents. No licenses. No approval needed.
Principle: Generosity enables adoption. Give it away.
The "Worse is Better" Principle
Richard Gabriel (1989):
"Simplicity is the most important consideration in a design."
The Two Philosophies
| MIT/Stanford ("The Right Thing") | New Jersey ("Worse is Better") |
|---|---|
| Correctness is paramount | Simplicity is paramount |
| Consistency matters | Interface should be simple |
| Completeness required | 80% solution acceptable |
| May sacrifice simplicity | May sacrifice correctness |
Why "Worse" Wins
The simpler thing:
- Gets implemented faster
- Gets adopted more easily
- Gets modified more readily
- Survives longer
Examples:
- Markdown beat Textile (simpler, less precise)
- JSON beat XML (simpler, less expressive)
- JavaScript beat Java in browsers (simpler, less typed)
- Unix beat Multics (simpler, less secure)
The Lesson
"If you're using ALL of C++ in your projects you're 'doing it wrong.' It is not a well-designed language." — @calmbonsai, Hacker News
Complex formats that aren't fully used are worse than simple formats fully used.
Postel's Law in Format Design
"Be liberal in what you accept, and conservative in what you send."
For Parsers
Accept:
- Variant spellings
- Missing optional fields
- Extra whitespace
- Unknown extensions
For Generators
Output:
- Canonical form
- Complete required fields
- Minimal complexity
- Maximum compatibility
The Superset Pattern
From HN:
"CommonMark Markdown is a rough superset of HTML, like how YAML is a superset of JSON."
Successful formats often nest:
- Markdown ⊃ HTML
- YAML ⊃ JSON
- JSX ⊃ JavaScript
Benefit: Easy migration path from simpler format.
Case Studies
Markdown (2004) — Won
| Factor | Score |
|---|---|
| Brand | ✅ Clever name |
| Problem | ✅ HTML too verbose |
| Existing behavior | ✅ Email conventions |
| Champion | ✅ John Gruber |
| Community | ✅ Bloggers |
| Timing | ✅ Blog era |
| Simple | ✅ 10 minute learning curve |
| Inspectable | ✅ Raw = readable |
| Free | ✅ No restrictions |
Textile (2003) — Lost
| Factor | Score |
|---|---|
| Brand | ❌ Obscure name |
| Problem | ✅ Same as Markdown |
| Existing behavior | ⚠️ Some |
| Champion | ⚠️ Dean Allen (less visible) |
| Community | ⚠️ Smaller |
| Timing | ✅ Same era |
| Simple | ⚠️ Slightly more complex |
| Inspectable | ✅ Yes |
| Free | ✅ Yes |
XML (1998) → JSON (2002)
| XML | JSON | |
|---|---|---|
| Verbosity | High | Low |
| Types | Complex | Simple |
| Parsing | Hard | Easy |
| Learning | Weeks | Hours |
| Adoption | Declined | Dominant |
Designing for MOOLLM
When creating new formats (skill cards, room files, etc.):
Checklist
- Name — Memorable? Self-explanatory?
- Problem — Clear, specific pain point?
- Existing behavior — Building on something familiar?
- Community — Who will help?
- Simplicity — Can you remove more?
- Inspectable — Learnable by example?
- Free — No restrictions?
Format Smell Tests
Red Flags:
- Requires documentation to understand examples
- Has more than 5 required fields
- Uses abbreviations or codes
- Needs special tools to view
- Includes binary components
Green Flags:
- One example teaches the format
- Readable without rendering
- Extensible without breaking
- Works with standard tools
The Community Point
From Anil:
"The people who make the real Internet and the real innovations also don't look for ways to hurt the world around them, or the people around them."
Formats succeed when:
- Created to solve the creator's own problem
- Shared freely for others' benefit
- Refined through feedback
- Not used to extract rent
Generosity scales. Greed doesn't.
Dovetails With
- markdown/ — Case study in success
- yaml-jazz/ — MOOLLM's data format
- plain-text/ — The substrate
- postel/ — Liberal parsing
- k-lines/ — K-lines (symbolic activators)
Protocol Symbol
FORMAT-DESIGN
Invoke when: Designing new formats, evaluating existing ones, choosing between options.
The Bottom Line
"Nearly every bit of the high-tech world, from the most cutting-edge AI systems at the biggest companies, to the casual scraps of code cobbled together by college students, is annotated and described by the same, simple plain text format."
That format wasn't designed by a committee. It was created by one person to solve their own problem, tested by a teenager, and given away for free.
Design like that.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.