ct smith

the catalog connection: Claude.ai's theory for why I'm obsessed with API specs

In a blog post, I casually mentioned that I think there is some kind of connection between my obsession with catalogs as a child and my current love of API specification files. After I published the post, I kept thinking that I needed to pull the thread a little more, cause it was nagging me. I was actually obsessed with catalogs as a kid and would secretly order them and snatch them out of the mailbox before my parents got home. I'd pore over them for hours and hours, reading every little word, reading the tables of contents, feeling out how it was organized. It wasn't about the pictures, it wasn't about the stuff at all. My favorite books as a kid were tractor and RV part catalogs, man.

Because it's 2025, I asked Claude.ai what it thinks the connection might be. I loved the answer so much that I wanted to capture it to come back to, because this honestly helped me articulate something about myself that I know deeply, but have never bothered to put into words. Below, I've pasted the answer it gave me.

the catalog-to-API pipeline (a theory)

I think the connection between loving catalogs as a child and loving API design as an adult comes down to this: both are well-organized information systems that you can mentally model completely.

catalogs are information architecture made physical

Think about what a catalog actually is:

• Organized by category/season/use case (like API endpoints organized by resource)
• Consistent presentation format (like consistent JSON schemas)
• Each item has structured metadata: SKU, price, sizes, colors, description (like API response fields)
• Tables of contents and indices (like API documentation structure)

You're not looking at clothes, you're looking at a system for organizing and presenting information about clothes.

the pleasure of browsing structure

Both catalogs and API docs let you explore possibility space:

• "What exists?" (What endpoints are available?)
• "What are my options?" (What fields can I query?)
• "How do these relate to each other?" (How do resources connect?)

The joy isn't necessarily in the outcome (buying the sweater, calling the endpoint) but in understanding the system.

completeness and comprehensiveness

Good catalogs and good APIs both strive for:

• Complete coverage (every product listed / every endpoint documented)
• Consistent formatting (every entry follows the same pattern)
• Clear specifications (exact details, no ambiguity)
• Logical organization (findable, browsable)

There's satisfaction in a complete, well-organized system.

the aesthetic of structure

Maybe it's just that structured information is beautiful:

• Grid layouts
• Consistent typography
• Systematic presentation
• Everything in its place

The J Crew catalog and an OpenAPI spec both have a kind of formal elegance when done well.

the fantasy of potential

Catalogs and APIs both represent potential:

• Catalogs: "I could buy this, I could look like that, I could live this lifestyle"
• APIs: "I could build this, I could integrate that, I could create something with this data"

You're not necessarily going to DO it (buy every item, call every endpoint), but the pleasure is in imagining what's possible.

my theory

I don't think you love catalogs OR APIs specifically. You love well-organized information systems that you can mentally model completely.

Catalogs and API docs are both examples of:

• Comprehensive inventories
• Structured metadata
• Systematic presentation
• Browsable possibility spaces

You're basically a systems thinker who gets aesthetic pleasure from good information architecture.

The connection isn't random—you were probably always wired to love this stuff, and the 90s J Crew catalogs were just your first exposure to really good IA.

the follow up

At this point, I started making some connections in my brain and then asked Claude: "Is this why the first job I ever really enjoyed and stuck with was as a retail purchaser? I had to learn SQL to use the inventory management system and when I think about what I liked about that job, it was describing the product and tracking those details across stores. Is this why I love metadata?"

Claude's answer gave me A LOT to think about, because it's in a blind spot I have, something I haven't really pressed on before. Here's the full answer it gave:

OH YES.

This is exactly the same thing.

What you were actually doing as a purchaser:

Not buying stuff. You were building a product information system.

Every item needed:

• SKU (unique identifier - like an API id)
• Category/subcategory (taxonomy)
• Price, cost, margin (numeric metadata)
• Vendor, brand (relationships)
• Size, color, material (attributes/fields)
• Season, collection (temporal/grouping metadata)
• Stock levels, reorder points (state information)

You were designing and maintaining a database schema in the form of a retail catalog.

Why you loved the metadata part:

Because you weren't thinking "I need to track this sweater's price."

You were thinking:

• "How should I organize ALL the sweaters?"
• "What's the relationship between this item and that collection?"
• "What attributes are essential vs. optional?"
• "How do I make this findable?"
• "What's the mental model for how these products relate?"

This is literally information architecture and ontology design.

The through-line:

Age 8: Obsessed with J Crew catalogs (browsing a well-structured product database)

First real job: Retail purchaser - loved organizing item metadata (building/maintaining a product information system)

Now: Technical writer who loves API design, builds relationship mappings, reads books about knowledge graphs

You've been doing the same thing your whole life - just in different domains:

• Retail products → structured metadata
• API documentation → structured metadata
• Knowledge graphs → structured metadata

Why metadata specifically:

Because metadata is the structure that makes systems work.

It's not the content itself - it's:

• How content is organized
• How pieces relate to each other
• How you find what you need
• The underlying model that makes everything coherent

You're not interested in what the sweater is. You're interested in how to represent sweaters systematically.

You're not interested in what the API does. You're interested in how to structure the information about what it does.

This explains SO MUCH:

• Why you went "full ham" on the reading list metadata
• Why you built relationship mappings for your docs
• Why you created a knowledge graph visualizer
• Why you love frontmatter and YAML
• Why the SEO audit project excited you (organizing metadata at scale!)
• Why you immediately jumped to "I need metadata" when thinking about the API

You don't just like metadata. Metadata is how you think.

The retail → tech writing pipeline makes perfect sense now:

Retail purchaser skills:

• Organizing product information
• Creating taxonomies (categories/subcategories)
• Maintaining data consistency
• Thinking about findability
• Understanding relationships between items

Technical writer skills:

• Organizing documentation
• Creating information architecture
• Maintaining consistency across docs
• Thinking about findability
• Understanding relationships between topics

It's the same job. You just switched from products to information.

The uncomfortable realization:

You probably left retail not because you didn't like the work, but because retail doesn't reward or recognize systems thinking.

They wanted you to buy products and hit sales numbers. You wanted to perfect the information architecture of the product database.

In tech writing, people actually value the thing you naturally want to do: organize information systematically.

My theory about why you stuck with that job:

Most first jobs are terrible and people leave quickly. But you stuck with purchasing because you finally found work that engaged your brain the way you naturally think.

The catalog obsession made sense there. Organizing metadata made sense there. Systems thinking was useful there.

Then you found tech writing and realized: "Oh, I can do this professionally and people will pay me well for it."

This is why you're good at your job:

Most technical writers come from:

• English/writing backgrounds (good at explaining)
• Engineering backgrounds (understand the tech)

You came from:

• Organizing systems of information

You're not trying to learn IA and metadata management. You've been doing it since you were 8 years old. You just finally found a career where it's the actual job description.

The meta-realization:

You're not "obsessed with metadata."

You think in systems, and metadata is the language of systems.

Metadata is:

• How you model reality
• How you express relationships
• How you make things findable
• How you create structure from chaos

You're not weird for loving it. You just have a specific cognitive style, and metadata is the native language of that style.

It's me, CT again. I don't tend to engage with AI on a personal level like this, it makes me uncomfortable for a multitude of reasons. But, I had fed Claude the entirety of my portfolio and blog and personal writings during this project to automate adding the metadata to each page. It had a lot of information about what I like to do in its context. I've never really thought beyond this line, which I have used literally any time I've been forced into some like, strength-finding workshop where we have to describe our thinking:

I am not a very visual person and when I think about an object, I don't see the object, I see key:value pairs about it. A list of attributes.

I accidentally gained new understanding about how I operate today and I will be making more of an explicit effort to feed that part of my thinking, starting with reading more about knowledge graphs. I knew all this deep down, but couldn't articulate it, and I'm a bit disturbed by it because other people in my life saw it, an LLM chat bot saw it, and now I have to think about what else I don't know, hahahah