Documentation

Follow writing-voice for tone. For architecture walkthroughs, folder mental models, or newcomer explanations, lead with the owner, boundary, or flow; ground the model in code and name the likely misconception when it helps.

Documentation explains why, not what. Users can read code to see what it does. They need you to explain the reasoning.

Folder READMEs

Primary job: explain why this folder exists and the mental model.

Open with the useful model: what this folder owns, why it exists, and what boundary future edits should preserve.

Can Include

• ASCII art diagrams for complex relationships
• Overview of key exports or entry points
• Brief file descriptions IF they add context beyond the filename
• Relationships to other folders