Skip to content

Rewrite building-an-adventure in a direct, guide-appropriate voice - #150

Merged
mmacy merged 1 commit into
mainfrom
rewrite-building-adventure
Oct 15, 2026
Merged

mmacy merged 1 commit into
mainfrom
rewrite-building-adventure

Conversation

@mmacy

@mmacy mmacy commented Oct 15, 2026

Copy link
Copy Markdown
Owner

What changed

Rewrote docs/getting-started/building-an-adventure.md to remove Claudish prose while keeping the guide's richer register. This page is a guide interior, not funnel-top, so it keeps its concept-explaining prose — but every sentence now earns its place.

Cut:

  • Meta-commentary about the document structure ("The complete program at the end runs as written...")
  • Over-explained edge-key mechanics (which cell keys which edge, the same-edge equivalence)
  • Justifying asides ("so you don't have to work out...", "Left unpinned, the engine rolls normally...")
  • Verbose enumeration ("optionally stuck or locked, optionally starting open, and optionally gated by an authored condition" → "stuck, locked, or gated")
  • Wordy transitions ("To learn about the gate you'd put on this door's requires field, see..." → "For gates, see...")
  • Exposition restating what the code shows (3-sentence walkthrough → 1 sentence)
  • "Where next" bullets tightened to noun phrases

What didn't change

All code is byte-identical (mechanically verified by diffing every fenced block). All cross-reference links preserved. The guide's richer register is intact in the tree list, keyed areas intro, content spec list, and validate section.

Verification

  • pytest tests/test_docs_examples.py — 319 passed, 73 skipped
  • mkdocs build --strict — clean

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
@mmacy
mmacy merged commit 38f8dbf into main Oct 15, 2026
5 checks passed
@mmacy
mmacy deleted the rewrite-building-adventure branch October 15, 2026 01:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant