I miss reltables, part 2
October 15, 2025
I wish all relationships had schemas
Yesterday, I posted a grand plan to add what amounts to a modern see also element built with a relationship mapping file (see part 1).
Now, let's think through the relationship schema I want to apply. So far, I know that I want the mappings to live separate from the content, so I'll put them in a file called relationships.yaml.
I still need to define the relationship types. After a little thought about our docs and developer resources, I came up with these relationship types:
- prerequisites - Must read before this doc
- leads_to - Natural next steps/implementations
- references - API references, error codes, specs to consult while working
- advanced - Deep dive topics for experienced users
- see_also - Related but parallel topics, like the UI version of a task covered in a developer guide
- not_confused_with - Disambiguation for commonly confused topics
The structure inside relationships.yml should look something like this:
relationships:
- topic: learning/guides/boarding-field-explorer
prerequisites:
- api-reference/api-overview
- learning/guides/merchant-onboarding
leads_to:
- api-reference/boarding
- developers/developer-guides/merchant-status-webhooks
references:
- developers/references/error-codes
not_confused_with:
- learning/guides/payment-processing
bidirectional:
- pair: [learning/guides/auth-capture, learning/guides/payment-processing]
relationship: see_also
note: "Auth/capture is WHEN funds move; processing is HOW"
I 1000% don't feel like starting from zero here so we're going to ask Cheap Claude (claude.ai) to write instructions for me to give Spendy Claude (Claude Code) to help me prep a test file real fast. Here's the prompt:
Hi there! I need to write some instructions for claude code to iterate over some docs to discern relationships, to create the relationship mapping for this project. Do you think there is an EASY and cheap way to do this for a test?
Claude.ai gave me a good prompt for this, I'm omitting it here cause it had some company-specific stuff from chat history. I ran the prompt and my first test attempt worked unbelievably well. However, I'm miserly when it comes to company money, and think I could be more efficent, so I asked Claude Code:
Do you think you could cross ref llms.txt and llms-full.txt to make this even cheaper to run?
As I've mentioned before, llms-full.txt strips out frontmatter and is just a wall of the text content of our docs. The good news is that llms.txt contains the URLs, descriptions, and titles so it can be indexed on! Claude Code indicated that it was a viable option, so I did a test run. It was super fast and pretty much on the nose for relationships. The recent SEO audit and improvements I made to the descriptions really helped Claude infer a lot of things correctly.
And finally, I pointed Claude Code to the YAML files that contain our docs navigation. I figured this would help it infer relationships to the API references, which generated from Fern definition files.
Claude Code and I exchanged ~4 messages about the strategy and then it scripted the generation. I ran the generation script and it did a pretty decent job creating a draft of the relationships! This worked out better and faster than I would have imagined possible. There's still a lot of human-in-the-loop stuff I need to do to really dial it in, but Claude's first pass got me off to a great start.
Okay now I've got my relationships.yaml. The next step is the script. I'll report on that in the next post.