consolidating some docs

README.md

@@ -23,13 +23,14 @@ Measure the effects:
 
 ![evaluating_impacts](docs/videos/evaluating_impacts.gif)
 
-## Documentation for developers
+## Documentation
 
-- [Developer guide](docs/dev.md)
-- [Map model](docs/articles/map/article.md)
-- [Traffic simulation](docs/articles/trafficsim/article.md)
-- [Rust implementation notes](docs/articles/rust/article.md)
-- [Running A/B Street in a new city](docs/new_city.md)
+- [How A/B Street works](docs/how_it_works.md)
+- Technical
+  - [Developer guide](docs/dev.md)
+  - [Map model](docs/articles/map/article.md)
+  - [Traffic simulation](docs/articles/trafficsim/article.md)
+  - [Running A/B Street in a new city](docs/new_city.md)
 - Presentations
   - April 2020 Rust meetup:
     [recording](https://www.youtube.com/watch?v=chYd5I-5oyc),
@@ -37,39 +38,12 @@ Measure the effects:
   - [Feb 2020 traffic sim](https://docs.google.com/presentation/d/181so6bWkGsPzpc-mI72CQffthMKMVzFPAkYxIyzgfAs/edit?usp=sharing)
   - [Oct 2019 Traffic sim and current challenges](https://docs.google.com/presentation/d/1PJRFoXmJAyenkqHIwo48zxqu1LSH6pc7XKSzhyC1raw/edit?usp=sharing)
   - [Oct 2019 Map construction](https://docs.google.com/presentation/d/1cF7qFtjAzkXL_r62CjxBvgQnLvuQ9I2WTE2iX_5tMCY/edit?usp=sharing)
+- Project
+  - [Roadmap](docs/roadmap.md)
+  - [Motivations](docs/motivations.md)
+  - [History](docs/history/history.md)
 
-## Features
-
-- The map
-  - A detailed rendering of Seattle from OpenStreetMap and King County GIS data,
-    including sidewalks, on-street parking, bike lanes, bus-only lanes, turn
-    lanes, buildings, and bus stops.
-  - Intersections governed by stop signs and traffic signals, with default
-    signal timings heuristically inferred. Hand-tuned geometry to reasonably
-    model Seattle's strangest intersections.
-  - You can adjust lane types, stop signs, and traffic signals, and reverse
-    lanes.
-- The traffic
-  - Individual cars, buses, bikes, and pedestrians move through the map.
-  - Most trips are multi-modal -- for example, a pedestrian exits a building,
-    walks a few blocks over to their parked car, drives somewhere, looks for
-    parking, and walks to their final destination.
-  - A realistic set of trips -- how many people go from building 1 to building 2
-    at some time using some form of transport -- based on
-    [PSRC's Soundcast](https://www.psrc.org/activity-based-travel-model-soundcast)
-    model.
-- The gameplay
-  - Start in sandbox mode, exploring the map, watching traffic patterns,
-    following individual agents, looking for problems.
-  - Jump to edit mode, where you can convert some on-street parking to bus lanes
-    and adjust traffic signals to try to fix some problem.
-  - Try your change in A/B test mode, running two traffic simulations
-    side-by-side. Explore how individual agents finish their trips faster or
-    slower, and compare aggregate results about different groups of traffic.
-  - Attempt a predefined challenge with particular objectives, like speeding up
-    certain bus routes or designing a full bike network.
-
-### Roadmap and contributing
+## Roadmap and contributing
 
 See the [roadmap](docs/roadmap.md) for current work, including ways to help. If
 you want to bring this to your city or if you're skilled in design, traffic
@@ -100,6 +74,7 @@ writes:
 
 Existing urban planning software is either proprietary or hard to use. A/B
 Street strives to set the accessibility bar high, by being a fun, engaging game.
+See [here](docs/motivations.md) for more guiding principles.
 
 ## Credits
 
@@ -108,11 +83,6 @@ Core team:
 - Dustin Carlino (<dabreegster@gmail.com>)
 - [Yuwen Li](https://www.yuwen-li.com/) (UX)
 
-Active contributors:
-
-- Orestis Malaspinas (<orestis.malaspinas@hesge.ch>) (pandemic modeling)
-- Christopher Klein (game design)
-
 Others:
 
 - Logo by [Ryan Pierson](https://www.ryandpierson.com/)
@@ -127,6 +97,8 @@ Others:
   have been great sounding boards for ideas since the beginning
 - In-game character faces adapted from
   [Anokhee Jandhyala](https://github.com/anokhee/visual-synthesizer)
+- Pandemic modeling by Orestis Malaspinas (<orestis.malaspinas@hesge.ch>)
+- Game design advice from Christopher Klein
 
 Data:
 

docs/articles/features/article.md

@@ -1,257 +0,0 @@
-# A/B Street Features
-
-Ever been on a bus stuck in traffic, wondering why there are cars parked on the
-road instead of a bus lane? This article overviews the features of A/B Street,
-an in-progress traffic simulation game set in Seattle. Players explore how small
-changes to road layout and intersection rules affect multi-modal trips of
-pedestrians, drivers, transit users, and cyclists. The game's mission is to make
-it fun and simple for anybody to test an idea to improve Seattle's traffic flow
-and, if the idea works well, to communicate it to others.
-
-Warning: This article last updated April 2019; screenshots have changed since
-then.
-
-<!--ts-->
-
-- [A/B Street Features](#ab-street-features)
-  - [Core gameplay](#core-gameplay)
-  - [Map](#map)
-    - [Lanes](#lanes)
-    - [Intersections (geometry)](#intersections-geometry)
-    - [Intersections (semantics)](#intersections-semantics)
-    - [Boundaries](#boundaries)
-    - [Buildings](#buildings)
-  - [Traffic simulation](#traffic-simulation)
-    - [Scale](#scale)
-    - [Trips](#trips)
-    - [A/B Tests](#ab-tests)
-  - [Ongoing work](#ongoing-work)
-
-<!-- Added by: dabreegster, at: Fri Apr 19 13:28:13 PDT 2019 -->
-
-<!--te-->
-
-## Core gameplay
-
-Explore Seattle and observe how traffic currently flows.
-
-![](screenshots/demo.gif)
-
-After finding a problem, edit the map in a few ways:
-
-- change lane types (example: replace on-street parking with a bus-only lane)
-- change which roads stop or yield at a stop sign
-- change the phases and timing of a traffic signal (example: ban a left turn or
-  give it a dedicated phase)
-
-![](screenshots/map_editing.gif)
-
-These are changes that could be prototyped in real life relatively cheaply. A/B
-Street's purpose is to explore improvements to Seattle that we could try
-tomorrow, not longer-term improvements like light rail extensions.
-
-After making edits, you can see how the same traffic patterns behave. I'm
-currently working on a way to easily visualize and compare results with and
-without edits. The game is currently more of a sandbox, but these phases of
-exploring, editing, and evaluating will be tied together in a more game-friendly
-format.
-
-## Map
-
-A/B Street generates a detailed map of Seattle from OpenStreetMap (OSM), King
-County GIS, and a few other sources. It takes lots of processing to make a map
-suitable for simulating traffic and that's visually appealing for a game. This
-section describes some of these problems and solutions.
-
-The portion of the code-base to transform and clean up the map are separate from
-the traffic simulation. If you see another use for this map, contact me and
-we'll figure out a format to export the data for your purposes. The code isn't
-Seattle-specific; most things work if you only feed in OpenStreetMap data, and
-plugging in another city's custom GIS data is probably not hard.
-
-### Lanes
-
-OSM models entire roads (crossing many intersections) coarsely, sometimes with
-some metadata about lane restrictions.
-
-![](screenshots/lanes_osm.gif)
-
-A/B Street breaks roads down into indidual lanes, automatically finding the
-geometry from the OSM road's center-line. Lane types and the number of lanes
-come from heuristics on the OSM metadata and from extra King County GIS
-shapefiles. Types of lanes include:
-
-- Regular driving lanes, usable by any vehicle
-- Sidewalks for pedestrian movement, including bus stops and paths to buildings
-- Bus- and bike-only lanes
-- On-street parking lanes, with individual parking spots
-
-![](screenshots/lanes_abst.gif)
-
-### Intersections (geometry)
-
-OSM doesn't explicitly model intersections at all; some roads just share points.
-
-![](screenshots/intersections_osm.gif)
-
-In A/B Street, lanes and intersections have disjoint geometry.
-
-![](screenshots/intersections_abst.gif)
-
-This means that cars and pedestrians stop and queue at the correct position
-before crossing an intersection.
-
-![](screenshots/moving_through_intersection.gif)
-
-The intersection geometry is calculated automatically, even for strangely-shaped
-cases.
-
-![](screenshots/intersection_good_geom.gif)
-
-OSM ways often have many "intersections" very close together. These appear as
-extremely short roads in A/B Street, which complicates traffic modeling.
-
-![](screenshots/short_roads_bridge_before.gif)
-
-These can be merged automatically, which works reasonably well sometimes.
-
-![](screenshots/short_roads_bridge_after.gif)
-
-But some cases are very complex; this is Montlake and 520 without merging short
-roads:
-
-![](screenshots/short_roads_montlake_before.gif)
-
-Montlake and 520 with merging doesn't look much better, so currently short road
-merging is still disabled.
-
-![](screenshots/short_roads_montlake_after.gif)
-
-Some highway on-ramps in OSM are modeled with particularly unusual geometry,
-overlapping an arterial road.
-
-![](screenshots/highway_onramp_osm.gif)
-
-A/B Street detects and fixes these cases.
-
-![](screenshots/highway_onramp_abst.gif)
-
-### Intersections (semantics)
-
-A/B Street models each turn through intersections, connecting an incoming lane
-to an outgoing lane. Some of these turns conflict, so cars can't perform them
-simultaneously. Currently stop signs and traffic signals are modeled
-(roundabouts act like all-way stops).
-
-For stop-sign controlled intersections, the bigger road by default has priority.
-
-![](screenshots/turns.gif)
-
-Intersections controlled by traffic signals have a default set of timed phases.
-Players can edit these.
-
-![](screenshots/traffic_signal.gif)
-
-### Boundaries
-
-How should the boundary of the map be handled? Without proper clipping, roads
-and lakes go out-of-bounds, often with very strange, long roads to nowhere.
-
-![](screenshots/clipping_before.gif)
-
-Proper clipping trims polygons to fit properly. Roads that cross the boundary
-terminate at special border intersections, which can model traffic flowing into
-or out of the map.
-
-![](screenshots/clipping_after.gif)
-
-### Buildings
-
-Light orange buildings are classified as residential, and dark orange as
-commercial. Additional data from King County GIS reveals how many units some
-apartments have. This could be used to generate a realistic number of trips
-between residential and commercial areas.
-
-![](screenshots/buildings.gif)
-
-## Traffic simulation
-
-A/B Street simulates the movement of individual agents:
-
-- Cars move along lanes in a queue, only changing lanes at intersections.
-- Buses are cars that cycle between bus stops, waiting at each one to unload and
-  load passengers.
-- Bikes are cars with a maximum speed limit.
-- Pedestrians move bidirectionally along sidewalks. They can pass through each
-  other; they don't queue or otherwise wait except at intersections. (Seattle
-  has very few places where pedestrian movement is significantly bottlenecked
-  due to other pedestrians.)
-
-![](screenshots/lots_of_agents.gif)
-
-### Scale
-
-A/B Street originally used a discrete timestep model, updating every agent every
-0.1 seconds. This was unnecessarily complex and too slow, so it now uses a
-discrete-event simulation, only updating agents when an interesting transition
-happens. So while a car crosses a long lane, its exact position is only
-interpolated for drawing, and a full update happens when the car reaches the
-intersection or the end of the queued cars.
-
-On my modest laptop (7th-gen Intel i5, 8GB RAM), I can simulate 10,000 agents on
-the small map at 2x speed (one minute of game-time in 30 seconds). This
-definitely needs improvement, but many interesting scenarios will be around this
-scale. Simulating ~800,000 agents in all of Seattle is not a high priority; the
-flow into and out of a smaller region can be modeled much more cheaply.
-
-A/B Street has a time-travel mode, useful for rewinding to trace the source of a
-bottleneck. This is a bit memory-intensive right now, but hasn't been updated to
-take advantage of the discrete-event model.
-
-![](screenshots/time_travel.gif)
-
-### Trips
-
-Most trips are multi-modal. A pedestrian will appear at a building, travel down
-the front path to the sidewalk, walk to a parked car they own or a bus stop,
-start driving or riding, park or deboard, and walk to their final destination.
-Bicycle trips have a fixed time to start or stop; this models how easy it is to
-find bike parking in Seattle. In contrast, car parking is often scarce, so
-drivers sometimes reach their destination, but start roaming around until they
-find an available spot.
-
-Trip generation -- travel from here to there, starting at this time, using a
-car/bike/bus -- is currently very unrealistic. Players can manually define
-groups of cars to spawn uniformly from somewhere within a region they outline,
-but this is tedious. I'm actively looking for data sources (like the U.S census)
-that'll give hints about where people live and work, to generate more realistic
-demand data.
-
-### A/B Tests
-
-Traffic simulation is fully deterministic -- run exactly the same scenario twice
-with the same version of the game, and you'll get the same results. Map edits
-like adding or removing parking will change the initial conditions minimally (so
-parked cars on unedited roads will usually not change). This lets players run
-meaningful A/B tests, holding everything fixed except for a few tweaks to lanes
-and intersections. Two simulations can be run in parallel, and there are tools
-to visualize how individual agents are taking different paths or moving
-faster/slower between the two runs.
-
-## Ongoing work
-
-A/B Street is not yet generally playable (but
-[if you want to anyway](/docs/INSTRUCTIONS.md)...):
-
-- The user interface to explore and edit the map is quite clunky.
-- The pieces of the game -- editing the map, running a simulation, comparing
-  results -- exist, but nothing is tied together yet in a game-like format.
-- Data sources describing a realistic set of trips is missing; cars start and
-  end at uniformly chosen places.
-- Some important things aren't yet modeled: light rail, big bike trails like the
-  Burke Gilman, ridesharing services, off-street parking lots and garages.
-
-If you're interested in joining me and working on problems like these, please
-get in touch. Funding is available. I also have half-finished articles with
-technical details about how A/B Street works; just ask me to finish them.
-Contact Dustin Carlino at <dabreegster@gmail.com>.

docs/articles/features/rewrite.md

@@ -1,61 +0,0 @@
-## Gameplay
-
-Most players will repeatedly:
-
-1) Start in sandbox mode, watching a traffic simulation and browsing around for problems.
-
-2) Use the map edit mode to change lane types and adjust intersections to try
-to fix some particular problem.
-
-3) Run an A/B test to compare how the same trips perform with and without some edits.
-
-## Parking
-
-On-street parking lanes are modeled, with the available spots based on the
-road's length. The blockface dataset from King County GIS is used to infer
-which roads have a parking lane -- but this dataset isn't meant to be so
-accurate, so the results are often incorrect.
-
-Driving trips between buildings (not starting or ending outside the map) are
-multi-modal: the trip starts with a pedestrian leaving a building by foot,
-walking to the closest parked car that they own, driving to their destination,
-and then wandering around to look for a free parking spot (which can take a
-while if there are no free parking spots nearby!). Simulations start with each
-building having some number of parked cars spawned somewhere close by.
-
-gif of ped entering a car
-gif of ped parking a car and going to a bldg
-
-TODO:
-- More accurate data for the number of cars associated with each household
-- Distinguish between types of on-street parking (free, pay by the hour, residences-only restrictions)
-- Off-street parking (driveways, public and private parking lots and garages)
-
-## Trips
-
-During a typical day in Seattle, where do people travel, when do they depart,
-and do they walk, bike, bus, or drive there? A/B Street imports trip data from
-PSRC's [Soundcast](https://www.psrc.org/activity-based-travel-model-soundcast),
-which models a synthetic population and has been carefully calibrated to match
-census data, travel surveys, landuse, vehicle counts, and so on.
-
-Mission Edit mode contains tools to visualize individual and aggregate trips
-from this data, without running a traffic simulation.
-
-gif of these tools
-
-TODO:
-- Trips that begin and end outside the boundary of a map, but pass through it,
-  are currently skipped. This happens often for trips passing through I5 or
-  520.
-
-## Map borders
-
-
-## Buildings
-
-home / commerical / mixed-use, etc. number of households and employees from psrc.
-
-## Generalizing to other cities
-
-anywhere with OSM data... reasonable defaults

docs/articles/rust/article.md

@@ -1,125 +0,0 @@
-# Notes on Rust in A/B Street
-
-This article describes parts of A/B Street's implementation that might be of
-interest to the Rust community.
-
-Background:
-[What is A/B Street](https://github.com/dabreegster/abstreet/blob/master/docs/articles/features/article.md)?
-
-<!--ts-->
-
-- [Notes on Rust in A/B Street](#notes-on-rust-in-ab-street)
-  - [ezgui](#ezgui)
-    - [Wizard and WrappedWizard](#wizard-and-wrappedwizard)
-  - [Test runner](#test-runner)
-  - [Grievances](#grievances)
-
-<!-- Added by: dabreegster, at: Mon Apr 22 15:46:36 PDT 2019 -->
-
-<!--te-->
-
-## ezgui
-
-After dabbling with the [existing GUI frameworks](http://areweguiyet.com/), I
-wound up rolling my own, highly specialized to my use case. I originally used
-Piston for underlying rendering, but I eventually switched to glium to stop
-uploading so much geometry constantly. A/B Street only makes use of OpenGL 3
-features and seems to work fine on Linux, Windows, and Mac. I don't have any
-interest in Vulkan and the other newer things, but would love to also get A/B
-Street running in the browser with WebGL or similar.
-
-The ezgui library exposes a very simple, immediate-mode API. There's no messy
-synchronization between application and GUI state; the application just asks
-what events happened and says what to draw. There are basic widgets for text
-entry and menus. The application creates and stores these, passes events along
-to them, and asks them to draw themselves. There's no layouting, besides options
-to align individual widgets. A "canvas" (really a 2D camera) handles basic
-panning and zooming.
-
-[This](https://github.com/dabreegster/abstreet/blob/eae301ee1bde247be5a2b067f6a4eadaa68aa6e7/synthetic/src/main.rs)
-is a simple example of usage. In the `event` method, the application checks its
-own current state and, based on that, tests for relevant key-presses or clicks.
-At the bottom of the screen, the current possible actions are shown with their
-hotkey -- a cheap context-sensitive help function. `draw` is simple as well;
-ezgui just exposes methods to draw a colored polygon and render text. Large
-batches of geometry can be uploaded once, then cheaply redrawn later.
-
-![](hotkeys.gif)
-
-One mildly hilarious feature I have to mention is the
-[screen capture](https://github.com/dabreegster/abstreet/blob/eae301ee1bde247be5a2b067f6a4eadaa68aa6e7/ezgui/src/widgets/screenshot.rs)
-tool. I wanted a way to visually compare the Seattle maps I'm rendering, so I
-can verify my changes to intersection layout code don't quietly butcher some
-part of the map I'm not looking at. I tried a few different ways of coercing
-glium to rendering to one big texture and saving to a file, but the result was
-extremely slow unless I compiled in release mode (which is absolutely not an
-option in the middle of debugging hairy geometry code). So instead, the
-application can ask the ezgui layer to zoom in some amount, then take a bunch of
-left-to-right, top-to-bottom steps over the canvas, calling an external
-screenshot tool after each render. Sometimes the quick hack works perfectly.
-
-I would consider cleaning up ezgui and publishing it as a generally usable
-crate, except it's pretty crippled:
-
-- basic widgets like a scrolling text box, list with radio buttons, and tables
-  are missing
-- The imperative style makes it quite easy for different parts of the UI to
-  stomp on each other, both using the same key. I'm not happy with how the
-  paradigm scales, and want to experiment with other solutions before leading
-  somebody else down the same hole I'm digging myself out of.
-
-I'm still unsure if I'll keep making ezgui handle the growing complexity of A/B
-Street's UI or if I'll try to adapt something else.
-
-### Wizard and WrappedWizard
-
-One trick I'm super proud of is the "wizard"-style dialogs for asking a series
-of questions. Suppose you have a struct with a bunch of fields, like
-[SpawnOverTime](https://github.com/dabreegster/abstreet/blob/eae301ee1bde247be5a2b067f6a4eadaa68aa6e7/sim/src/make/scenario.rs).
-You want to prompt the user to fill out this struct, maybe even branching the
-questions you ask based on previous answers.
-
-My solution to this problem is
-[edit_scenario](https://github.com/dabreegster/abstreet/blob/eae301ee1bde247be5a2b067f6a4eadaa68aa6e7/editor/src/plugins/edit/scenarios.rs),
-which is called once per event (keypress). This code is extremely easy to write
-and maintain; the complexity of the user prompts being filled out slowly over
-the course of many `event()` and `draw()` calls is invisible. The
-`WrappedWizard` works by storing confirmed responses and some widget
-representing the current question. So the first many rounds, the `choose_string`
-call for "What kind of edit" just defers to an ezgui Menu, which keeps its own
-state about the current selected item. Once the Menu is done, WrappedWizard
-stores the String response. The next time `choose_string` is called, it
-immediately returns that answer, so `edit_scenario` makes it to the next step.
-This is a simple way of simulating continuations. WrappedWizard returns `None`
-for incomplete answers, and the `?` short-circuiting takes care of the rest.
-
-## Test runner
-
-The Rust test runner is painful to use. When a test fails, I want STDOUT and
-STDERR in a log file, not inlined with information on test runs. I sometimes
-want to surface a custom string in the main test results that lets me quickly
-re-run a failed test with a GUI. So I wrote
-[this](https://github.com/dabreegster/abstreet/blob/eae301ee1bde247be5a2b067f6a4eadaa68aa6e7/tests/src/runner.rs)
-to solve my needs, at least until https://github.com/rust-lang/rust/issues/50297
-makes progress.
-
-![](tests.gif)
-
-The downside is that all test code has to live in one crate, but I'm sure some
-macro cleverness could avoid this.
-
-## Grievances
-
-No surprises here: compile times suck. It's especially frustrating to add a few
-lines to `geom` for debugging (not affecting any of the crate's external APIs),
-then wait for the dependent crates `map_model`, `sim`, and `game` to recompile
-(or maybe just link again, but it sure is slow). It's also frustrating to
-recompile all dependencies from scratch when I switch between compiling for
-Linux and Windows.
-
-There are a few crates with binary heaps for priority queues, but I couldn't
-make any of them work with Serde, have deterministic behavior (so no hashing
-underneath), and act as a min-heap instead of a max-heap.
-
-Otherwise, Rust is amazing! Sometimes the borrow checker makes me express
-something awkwardly, but mostly it's forced me to avoid bad ideas.

docs/assumptions.md

@@ -1,60 +0,0 @@
-# Modeling assumptions
-
-This is pretty disorganized right now, just need to start something.
-
-## Sidewalk connectivity
-
-Should it be possible to close sidewalks for construction? Right now, this
-breaks too many assumptions that're hard to recompute. Building front paths and
-bus stops are associated with a sidewalk, so that makes applying the edit way
-more unclear. Closing intersections is still useful -- remove all of the vehicle
-turns, but allow the walking turns.
-
-## Graph connectivity
-
-For now, no map edits should be able to impact any of the trips possible in the
-baseline -- so no impacting graph connectivity, no killing bus stops, etc.
-
-## Over-taking
-
-Unsupported right now, but it should happen. Unlocks shared bike/ped trails like
-the Burke.
-
-## Left turns in the middle of a road
-
-Into a driveway, or using the shared left turn lanes. This should be supported.
-Parking and unparking already have the ability to block one queue -- extend
-that.
-
-## Demand modeling
-
-When the player makes it much more/less convenient to take some trip, people
-will eventually shift mode or take different trips altogether. Not attempting
-any of that yet -- just using PSRC trips. I don't understand the demand modeling
-process well at all yet.
-
-## Bike/bus lane connectivity
-
-Bikes and buses can make crazy left turns from the rightmost protected lane.
-Alternatively, stop generating those turns and start generating turns between
-protected and general lanes.
-
-## Parking
-
-No restrictions -- all available spots are treated equally. No cost, time
-limits, or private spots.
-
-## U-turns
-
-Only happen at dead-ends right now. But there are a few important ones to
-support -- like Montlake Blvd to go WB on 520.
-
-## Roads without sidewalks
-
-Last-leg routing... pedestrians need to walk on the road. How to model this?
-Happens in Seattle when there's parking without sidewalks nearby.
-
-## One-at-a-time roads
-
-Some roads are "two-way", but have parking on both sides, and so are effectively
-one way at a time. How's this tagged in OSM? How do we model this?

docs/history/history.md

@@ -11,8 +11,10 @@ has been festering since I was about 16.
       * [Year 1 (June 2018-2019)](#year-1-june-2018-2019)
       * [Year 2 (June 2019-2020)](#year-2-june-2019-2020)
       * [Retrospective](#retrospective)
+      * [Trivia](#trivia)
+
+<!-- Added by: dabreegster, at: Mon Jun  8 12:16:39 PDT 2020 -->
 
-<!-- Added by: dabreegster, at: Sat May 30 15:43:02 PDT 2020 -->
 <!--te-->
 
 ## Backstory
@@ -23,12 +25,12 @@ quick version.
 
 I grew up in Baton Rouge, where driving is effectively the only mode of
 transport. (I've gone back and made a point of taking long walks to confirm how
-antagonistically the city is designed towards other modes.) Very early on, I
-fell in love with a Nintendo 64 game called Banjo Kazooie, which led me to the
-online fan communities of the early 2000's. I wanted to create games too, so I
-started learning programming via library books and lots of questions on IRC.
-Because I never had any confidence in art, I wound up working on roguelikes,
-which led to a fervent interest in pathfinding algorithms and
+antagonistically the city is designed towards walking.) Very early on, I fell in
+love with a Nintendo 64 game called Banjo Kazooie, which led me to the online
+fan communities of the early 2000's. I wanted to create games too, so I started
+learning programming via library books and lots of questions on IRC. Because I
+never had any confidence in art, I wound up working on roguelikes, which led to
+a fervent interest in pathfinding algorithms and
 [collaborative diffusion](http://www.cs.colorado.edu/~ralex/papers/PDF/OOPSLA06antiobjects.pdf).
 When I started driving in high school, I quickly realized how bad people were at
 it. I remember being stuck at the intersection of
@@ -111,6 +113,7 @@ calling out milestones. "UI churn" is pretty much constantly happening.
   test runner framework
 - December: bezier curves for turns, traffic signal editor, a first attempt at
   merging intersections, right-click menus, a top menu, modal menus
+
   - the grand colorscheme refactor: a python script scraped `cs.get_def` calls
     at build-time
 
@@ -139,6 +142,7 @@ calling out milestones. "UI churn" is pretty much constantly happening.
 - September: offstreet parking, associating parked cars with buildings using
   Soundcast (before that, anybody could use any car!), implemented texture
   support for some reason, doing manual `MapFixes` at scale to fix OSM bugs
+
   - **milestone**: got the smallest montlake map to run without gridlock
 
 - October: parking sim fixes, opportunistic lane-changing, starting challenge
@@ -148,6 +152,7 @@ calling out milestones. "UI churn" is pretty much constantly happening.
   - **milestone**: Yuwen joins project
 - December: the UI reform begins (flexbox, minimap, trip timelines, cutting over
   to SVGs, info panels, scrolling), started naming releases sensibly
+
   - Project leaked to [HN](https://news.ycombinator.com/item?id=21763636), woops
 
 - January: UI reform continues, the modern tutorial mode appears
@@ -180,4 +185,6 @@ What poor judgments have cost me the most time?
 
 ## Trivia
 
-The name was almost "Unstreet" or "Superban" (superb urban)
+- The name was almost "Unstreet" or "Superban" (superb urban)
+- I hope you enjoy and/or are baffled by the
+  [release names](https://github.com/dabreegster/abstreet/releases)

docs/how_it_works.md

@@ -1,56 +1,146 @@
 # How A/B Street works
 
-The big caveat: I'm a software engineer with no background in civil engineering.
-A/B Street absolutely shouldn't replace other planning or analysis. It's just
-meant to be an additional tool to quickly prototype ideas without expensive
-software and formal training.
+The overview:
 
-This page gives a non-technical overview. See
-[here](https://github.com/dabreegster/abstreet/#documentation-for-developers)
-for details.
+1.  A detailed map of Seattle is built from
+    [OpenStreetMap (OSM)](https://www.openstreetmap.org/about)
+2.  A realistic set of daily trips by car, bike, foot, and bus are simulated
+3.  You make small changes to roads and intersections
+4.  You explore how these changes affect the trips
 
-## The map of Seattle
+Details below. Many limitations are mentioned; improvements are ongoing. I'll
+add pictures to explain better when I get time.
 
-The map in A/B Street is built from
-[OpenStreetMap](https://www.openstreetmap.org/about). You will notice many
-places where the number of lanes is wrong; let me know about these, and we can
-contribute the fix to OpenStreetMap. Many sidewalks and crosswalks are also
-incorrectly placed.
+<!--ts-->
+   * [How A/B Street works](#how-ab-street-works)
+      * [Driving](#driving)
+      * [Parking](#parking)
+      * [Biking](#biking)
+   * [Walking](#walking)
+      * [Transit](#transit)
+      * [Intersections](#intersections)
+      * [People and trips](#people-and-trips)
+      * [Map edits](#map-edits)
 
-People in A/B Street have to park their cars somewhere. I can't find good data
-about either public or private parking. For now, I'm using a Seattle
-[GeoData blockface dataset](http://data-seattlecitygis.opendata.arcgis.com/datasets/blockface)
-to guess on-street parking, but this is frequently wrong. I'm assigning every
-building one offstreet spot. This is wildly unrealistic, but I have nothing
-better yet.
+<!-- Added by: dabreegster, at: Mon Jun  8 12:17:13 PDT 2020 -->
 
-There's also no public data about how traffic signals in Seattle are timed. I'm
-making automatic guesses, and attempting to manually survey as many signals
-in-person as I can. I could really use help here!
+<!--te-->
 
-## The traffic
+## Driving
 
-Vehicles in A/B Street instantly accelerate and brake. They change lanes only at
-intersections, and they can't over-take slower vehicles in the middle of a lane.
-People walking on sidewalks can "ghost" through one another, or walk together in
-a crowd -- before COVID-19, this was a reasonable model in most areas. Despite
-these limits, I hope you'll find the large-scale traffic patterns that emerge
-from the simulation to be at least a little familiar from your real-world
-experiences.
+- Movement: no acceleration, go the full speed limit of the road unless there's
+  a slower vehicle in front
+- Lanes
+  - No over-taking or lane-changing in the middle of a road, only at
+    intersections
+  - Strange choice of lanes -- the least full at the time of arrival
+  - Narrow two-way neighborhood roads where, in practice, only one car at a time
+    can go are currently full two-way roads
+- Routing is based on fastest time assuming no traffic
+  - No rerouting if the driver encounters a traffic jam
 
-People in A/B Street follow a specific schedule, taking trips between buildings
-throughout the day. The trips come from
-[PSRC's Soundcast model](https://www.psrc.org/activity-based-travel-model-soundcast),
-which uses census, land-use, and vehicle count data to generate a "synthetic
-population" roughly matching reality. The trip data is from 2014, which is quite
-old.
+## Parking
 
-When you make changes to the map in A/B Street, exactly the people still take
-exactly the same trips, making the same decision whether to drive, walk, bike,
-or take transit. Currently, your changes only influence their route and
-experience along it.
+- Types
+  - On-street: parallel parking lanes from
+    [GeoData blockface dataset](http://data-seattlecitygis.opendata.arcgis.com/datasets/blockface)
+    and
+    [manually mapped](https://dabreegster.github.io/abstreet/map_parking.html)
+  - Off-street: most buildings have at least a few parking spots in a driveway
+    or carport
+  - Parking lots: the number of spots is inferred
+- Restrictions
+  - All spots are public except for the few spots associated with each building
+  - No time restrictions or modeling of payment
+- How cars park
+  - Drivers won't look for parking until they first reach their destination
+    building. Then they'll drive to the nearest open parking spot (magically
+    knowing what spots are open, even if they're a few blocks away). If somebody
+    else has taken the spot when they arrive, they'll try again.
+  - Once a driver finds an open spot, they'll take 10-15 seconds to park. They
+    block the road behind them in the meantime. There are no conflicts between
+    pedestrians and cars when using a driveway. Cars won't make left turns into
+    or out of driveways.
+- Some parking along the boundary of the map is "blackholed", meaning it's
+  impossible to actually reach it. Nobody will use these spots.
 
-## Missing things
+## Biking
 
-Light rail, shared biking/walking trails like the Burke Gilman, and ridesharing
-are some of the notable things missing right now.
+- Choice of lane
+  - Multi-use trails like the Burke Gilman and separated cycle-tracks like the
+    one along Broadway are currently missing
+  - Cyclists won't use an empty parking lane
+  - On roads without a bike lane, cyclists currently won't stick to the
+    rightmost lane
+  - No over-taking yet, so cars can get stuck behind a bike even if there's a
+    passing lane
+- Elevation change isn't factored into route choice or speed yet; pretend
+  everybody has an e-bike
+- Beginning or ending a cycling trip takes 30-45 seconds. Locking up at bike
+  racks with limited capacity isn't modeled; in practice, it's always easy in
+  Seattle to find a place to lock up.
+
+# Walking
+
+- Not using sidewalk and crosswalk data from OSM yet
+- No jay-walking, even on empty residential streets
+- Pedestrians can't use roads without sidewalks at all
+  - When a road only has a sidewalk on one side, driveways will cross the road
+- Pedestrians can "ghost" through each other; crowds of people can grow to any
+  size
+
+## Transit
+
+- The modeling of buses is extremely simple and buggy; I'll work on this soon
+- No light rail yet
+
+## Intersections
+
+- Conflicting movements are coarse: a second vehicle won't start a conflicting
+  turn, even if the first vehicle is physically out of the way but still
+  partially in the intersection
+- Most of the time, vehicles won't "block the box" -- if there's no room in the
+  target lane, a vehicle won't start turning and risk getting stuck in the
+  intersection
+- Traffic signals
+  - Only fixed timers; no actuated signals or
+    [centralized control](https://www.seattle.gov/transportation/projects-and-programs/programs/technology-program/mercer-scoot)
+    yet
+  - The timing and phases are automatically guessed, except some intersections
+    are
+    [manually mapped](https://docs.google.com/document/d/1Od_7WvBVYsvpY4etRI0sKmYmZnwXMAXcJxVmm8Iwdcg/edit?usp=sharing)
+  - No pedestrian beg buttons; walk signals always come on
+  - The signal doesn't change for rush hour or weekday/weekend traffic; there's
+    one pattern all day
+- Turn restrictions from OSM are applied
+  - Per lane (left turn only from leftmost lane), entire roads, multiple
+    intersections
+
+## People and trips
+
+- A "synthetic population" of ~700,000 people come from
+  [PSRC's Soundcast model](https://www.psrc.org/activity-based-travel-model-soundcast)
+  - Soundcast uses census, land-use, vehicle counts, and commuter surveys. The
+    current data is from 2014.
+  - All driving trips are currently single-occupancy; no car-pooling or
+    ridesharing
+  - Parked cars are initially placed at midnight based on the number of trips
+    between buildings
+- Each person's schedule never changes
+  - Your changes to the map won't yet convince somebody to take a bus or walk
+    instead of drive
+
+## Map edits
+
+- Types of edits
+  - Change types of lanes. Sometimes this is unrealistic based on actual road
+    width, but data for this is unavailable.
+  - Reversing direction of lanes
+  - Changing stop signs
+  - Changing traffic signal timing
+  - Closing roads and intersections for construction, forcing rerouting
+- Disconnecting the map
+  - Generally you can't close sidewalks or make changes to make buildings
+    unreachable
+  - You shouldn't be able to make bus stops unreachable, but currently this is
+    buggy

docs/motivations.md

@@ -44,7 +44,7 @@ these here. In no particular order:
   land-use patterns handle population growth better.
 
 - **Compromise and trade-offs**: I see lots of rhetoric calling for extreme,
-  sudden change. I don't want to ban all cars, because that's not realistic. I
-  want to focus on immediate steps forward. I want to come up with estimates
-  about impacting drivers by a median 3 minutes in order to save a bus route 1
-  minute, and to shift public discourse towards that.
+  sudden change. I don't want to ban all cars from downtown Seattle, because
+  that's not realistic. I want to focus on immediate steps forward. I want to
+  come up with estimates about impacting drivers by a median 3 minutes in order
+  to save a bus route 1 minute, and to shift public discourse towards that.