Documentation

While documenting UX flows with Rails + Lookbook, I hit a moment of “something feels off.” Each Step only showed wireframe fragments, so looking at the Lookbook list gave zero sense of the overall flow. I fixed two things: Add a Mermaid flowchart Overview step to each flow Redesign all Step template structures The Problem: Lookbook Step Previews Feel Like “Context-Free Fragments” # @label Admin UX Flow # @logical_path ux_flows class UxFlows::AdminFlowPreview < ViewComponent::Preview # @label 1. Login -> Admin Dashboard def step_1_login_dashboard render_with_template end # ... end Each step_* method renders an ERB template via render_with_template. The ERB contains a wireframe with a simple step navigation bar at the top. ...

After running a project for nearly a year, documents accumulate. Feature design specs, TODOs, debugging records, migration plans, test scenarios… Each was needed at the time, but over time they become noise. One day I ran find docs -name "*.md" | wc -l and got 2,352. Status Check: How Did It Get This Bad find docs -name "*.md" | wc -l # 2352 # File count by directory find docs -maxdepth 1 -type d | while read d; do count=$(find "$d" -name "*.md" | wc -l) echo "$count $(basename $d)" done | sort -rn | head -15 Results: ...