filling out some instructions for the binary releases. also writing down

some interview questions / actual tasks for a UX person I'd love to
hire. :)

INSTRUCTIONS.md

@@ -1,6 +1,46 @@
 # A/B Street Instructions
 
-...
+General disclaimer: This is a very rough demo. The user interface and controls
+are horrible. Don't expect things to work well, or at all. Please email
+`dabreegster@gmail.com` or file a Github issue if you hit problems.
+
+Start the game by running `run_montlake.sh` or `run_montlake.bat`. On Windows,
+you'll probably get a warning about running software from an unknown publisher.
+Two maps are included in this release -- `montlake` is a small slice around the
+Montlake neighborhood, `23rd` is a larger slice around 23rd Ave.
+
+General controls:
+
+- Click and drag to move
+- Scroll wheel or touchpad to zoom
+- Hover over something and hold Control to examine it
+- Select something and right click for a menu of relevant actions. The keyboard
+  shortcuts also work just by selecting that object.
+- Explore the menu bar at the top.
+
+Simulating traffic:
+
+- Choose `seed the sim with agents` from the `Simulation` menu, or just press
+  `s` while nothing is selected. This will spawn a bunch of parked cars, buses,
+  and pedestrians leaving buildings. Some of the pedestrians will get into a
+  parked car and start driving somewhere.
+- Press `space` to pause/resume the simulation. `]` speeds things up, and `[`
+  slows things down. You can find all of these in the `Simulation` menu.
+- Spawn a single agent by selecting the starting building and pressing `F3` (or
+  right clicking the building and using the menu). Select the goal building and
+  confirm with `F3`. You can hover over any agent to see its route; press `r`
+  (or right-click the agent) to keep drawing the route.
+- Hover over an intersection and press `z` to spawn a bunch of cars nearby.
+
+Editing the map:
+
+- You can only make edits when a simulation isn't running. If you already
+  started one, quit and start over.
+- Select an intersection and press `e`. You can then select an individual turn
+  icon and press `space` to change its priority.
+- Enable `edit roads` from the `Edit` menu, select a lane, and press `space` to
+  change its type.
+- Save your changes using `manage map edits` in the `Edit` menu.
 
 ## Data source licensing
 

docs/design/map.md

@@ -10,28 +10,36 @@ link to code
 
 ## Features
 
-demonstrate all of these things with before/after pictures or GIFs showing functionality
+demonstrate all of these things with before/after pictures or GIFs showing
+functionality
 
 - Lanes
   - show OSM way with metadata
-  - then multiple lane types, between two intersections. example with a curved road.
+  - then multiple lane types, between two intersections. example with a curved
+    road.
   - individual parking spots modeled
-  - bus/bike lane restrictions modeled, with connecting turns that make sense (bus can go from restricted to general lane, but normal car cant enter a bus lane)
+  - bus/bike lane restrictions modeled, with connecting turns that make sense
+    (bus can go from restricted to general lane, but normal car cant enter a bus
+    lane)
 - Intersections
   - OSM model doesn't explicitly have these at all; just ways with shared nodes
-  - they have geometry; cars and peds stop and wait at the end of a lane, then cross through the intersection
+  - they have geometry; cars and peds stop and wait at the end of a lane, then
+    cross through the intersection
     - crosswalks and sidewalk geometry continues
   - turns connect lanes, the turns have a path. turns conflict or don't.
-  - stop signs (some directions stop and others dont), traffic signals with multiple phases
+  - stop signs (some directions stop and others dont), traffic signals with
+    multiple phases
     - "reasonable" defaults inferred, editor for the rest
   - WIP: small intersections, roundabouts merged
 - Buildings
   - classified by use, notion of residential density
   - front path connecting to a sidewalk
 - Clipping / borders (WIP)
-  - clipping polygon actually chops all geometry to fit -- doesnt just omit things that cross or leave dangling OOB stuff
+  - clipping polygon actually chops all geometry to fit -- doesnt just omit
+    things that cross or leave dangling OOB stuff
     - cleans up areas (parks, bodies of water) nicely
-  - roads that cross the boundary have direction-aware 'border intersections' at the end, to model traffic flowing in or out of an area
+  - roads that cross the boundary have direction-aware 'border intersections' at
+    the end, to model traffic flowing in or out of an area
 
 ## Model
 

docs/project/team.md

@@ -0,0 +1,20 @@
+# Desired team
+
+## UX
+
+- How should compatible functionality (like following an agent and showing its
+  route) work simultaneously? What functions should remain mutually exclusive
+  (showing chokepoints and editing lanes)?
+- How should the modal side menus, bottom status bar, right click menus, top
+  menu, etc be designed?
+- Is it confusing to let people edit a map while a simulation is running?
+- How should edits to a map be visualized?
+- How should traffic be depicted when unzoomed?
+- Please sketch how a traffic signal's current state be displayed. What about
+  editing a traffic signal?
+- How to show A/B test results live as a simulation runs?
+- Multiple overlapping pedestrians?
+- Redesign how cars look, including turn signals
+- How to depict demand data?
+- What would you change about the way the map is currently displayed? (Building
+  types, front paths, intersection colors, stop signs, colors)

release/linux.sh

@@ -11,6 +11,11 @@ cp color_scheme INSTRUCTIONS.md $OUT
 mkdir -p $OUT/data/maps
 for map in montlake 23rd; do
 	cp -v data/maps/$map.abst $OUT/data/maps/
+	cat << EOF > $OUT/run_$map.sh
+cd editor
+./editor ../data/maps/$map.abst
+EOF
+	chmod +x $OUT/run_$map.sh
 done
 
 mkdir $OUT/editor