a-b-street / docs

Technical and user documentation for A/B Street

A/B Street docs

This repo contains the source code (in Markdown format) of the technical documentation and user guides for A/B Street. We use mdbook for formatting, and have a Github action publish on every commit. Contributions to the docs, all of which you can find as .md files in the book/src folder of this repo, and which can be edited on GitHub are very welcome!

To build the book, download or clone the repo, e.g. using the gh CLI as follows:

git clone https://github.com/a-b-street/docs

Then you can change directory and start editing the files, e.g. with the following commands:

cd docs
edit book/src/tech/dev/api.md

That should open an editor with the contents of the api.md open, ready for you to edit. You can also edit the files such as the API documentation linked to above directly in GitHub.

The following commands will serve a locally hosted version of the book from the book folder (assuming you have Rust installed):

cargo install mdbook # install the mdbook crate used to serve the book
cd book
mdbook serve # serve book locally to dynamically update to show your changes

After running the commands above you should see a version of the docs at 127.0.0.1:3000/.

To keep the markdown files formatted the prettier npm package is used. Install it and run the formatting script as follows (on Ubuntu, replace apt with your package manager of choice):

sudo apt install npm
sudo npm install -g prettier
./format_md.sh

After your Pull Request has been accepted you will be able to see the deployed docs at https://a-b-street.github.io/docs.

docs's Issues

Add edit button

Inspiration: https://github.com/rust-lang/mdBook/blob/master/guide/book.toml#L14

Check #advocacy Slack channel for proposals

Broken Link under Project/Contributing/Transportation modelling

The hyperlink for [travel demand models] leads to an invalid URL error.

I think this is because the subfolder for Technical Details (tech) has been moved outside of the Project directory.

Download link for A/B Street is broken

The download link for A/B Street on https://a-b-street.github.io/docs/software/abstreet.html points to https://a-b-street.github.io/docs/howto/index.html, which is a page saying "Document not found (404)".

Landing page feedback

Copied from Slack with @dingaaling (with broken list formatting, urgh)

• Download links not at the top (and clearly marked with a 'Download here' Title
• Relevant emojis instead of bulletpoint marks, and maybe bold main text, e.g.

🚘 Understand how drivers may shortcut through neighbourhoods:three_button_mouse: Experiment with placing filters to create safer residential streets

• More line spacing between bulletpoints
• More focus on mission (especially first sentence), maybe above motivation?
• Clearer heirarchy on about page
• Maybe a Learn More on about
• Quotation mark missing at beginning of quote on about
• Could contact page have a contact form?
• Maybe not the biggest fan of the dark blue 😬 feel like for main background colours pale works better
• As there's only three options does the mobile nav need to be hamburger? Or can they be the same as for comp
• Could it all be on one page, with the nav bar linking with anchors?
• Less padding/margins on mobile - take up the space! But still aim for rule of 60ish characters per line of text
• Can about page be spiced up with visuals/icons? I can imagine points 1 & 2 having accompanying icons

I have one to add: the thumbnails below the carousel all have an outline except for the currently selected one. This is backwards from what I would expect; how about an outline only around the current?

Simple way to get accurate city boundaries

Currently the part about importing new city suggest

3. Use geojson.io or geoman.io to draw a boundary around the region you want to simulate and save the geojson locally.

Which is probably good enough for local use but painful if you want to capture the city accurately which you'd presumably want for permanently added cities.

It seems it would be more simple to

1. go to openstreetmap.org and search for the city
2. select the City / City Boundary / Municipality Boundary etc., one that is a type=boundary Relation such as https://www.openstreetmap.org/relation/271110
3. copypaste the number to http://polygons.openstreetmap.fr/ (sample)
4. download the GeoJSON

Unfortunately "type": "GeometryCollection" on the toplevel causes an "unexpected geojson" panic, so

5. paste the GeoJSON to geojson.io
6. draw a rectangle and delete it
7. copy the now acceptable GeoJSON

Rewrite Lake Wash proposal

We can model it properly as access restrictions now, and can maybe fit to the template better

More detailed instructions on running the tool on Linux

Aimed at beginners struggling with the concise instructions at https://a-b-street.github.io/docs/user/index.html

Mention GUI to import data for area in docs

Importing data is covered here: https://a-b-street.github.io/docs/tech/map/importing/index.html

Easiest way to get new map data is from the GUI, worth mentioning that.

Make json example more minimal

The current example in the docs represents a trip spanning 100+ miles it seems!

Can we have a more minimal example, that fits in the Montlake case study area, for the docs please?

https://a-b-street.github.io/docs/tech/dev/formats/scenarios.html

Documentation: Missing videos?

In abstreet there are some missing images and videos.

Here is one example.

I'm not sure if it is supposed to be like this.

PS: Unrelated: Where can I read about the implemented models? I'm especially interested in the pedestrian models.

Landing page broken on mobile

https://a-b-street.github.io/docs/landing_page/

from @dingaaling:

Pretty sure the fault lies with Grid or ResponsiveAppBar's pop out menu on the right side

Redesign front page and user-facing website

Currently abstreet.org lands people on the Github page, which

1. scares off some people, because if they scroll up, they see code
2. is horribly outdated with ancient GIFs and calls everything a "game"

I think https://a-b-street.github.io/docs/ is somewhat reasonably organized for the technical section, and that's about it... user-facing site/docs are tough. Main things a good website should probably do are communicating what we do, why, and how to get involved.

@natesheehan, any thoughts? Or any favorite websites that do a good job of introducing projects that we could model after?

Front page ideas

I imagine the first screenfull of stuff should include:

• the logo
• a quick summary of our 3 principles, which if I had to distill down
  • put planners, government stakeholders, and citizens all on equal footing with the same software
  • open source, public data
  • promote sustainable transportation
• maybe some kind of tag-line, like "inspire/imagine better transportation network, but get specific"
• a media carousel showing off impressive stuff, to hook people in

There are a bunch of different ways of breaking down what we do, and I'm not sure which ones belong.

• By piece of software
  • A/B Street (the main traffic simulator), the 15-minute neighborhood tool, the bike network planning tool, the new LTN tool, 15-minute Santa (an actual game), some tools specialized for the OSM community (I wouldn't even mention these upfront, niche audience)
• By "features"
  • https://a-b-street.github.io/docs/project/retrospective/index.html has a bunch of recent screenshots and GIFs
  • The Streetmix-style road editor, the traffic signal editor, you can simulate agents, you can generate travel demand models in a bunch of ways, the map is a detailed "digital twin" built from OpenStreetMap and other sources, all the dataviz stuff, etc
• By use case (kind of mixed in with grouping by audience...)
  • Telling data-driven stories (individual trips and aggregate trends in the Broadmoor article, showing usefulness of bike network extensions in the new tool)
  • Public communication, feedback (planners -> people)
  • Public engagement / citizen science (people -> planners)
  • Education / research (there are a few undergrads and grad students who've used parts of A/B Street in classes, their projects)

We could also focus on comparing ourselves to related software. If I had to summarize, our niche is rapid prototyping, aiming at a general audience, and being FOSS.

Another way to phrase things, related to use cases, is by problems:

• I have a bunch of examples of gov communicating plans to people in a poor way
• Likewise for people/advocacy groups communicating to gov

https://a-b-street.github.io/docs/project/presentations.html have introduced the project in many of these different ways. I'm not sure what'd be best for a website. The SUMO talk is probably one of the better project overviews.

Seed user guide from existing google doc

https://docs.google.com/document/d/1xb5VW09DgFeNxyMCVYg_uo_torqCBqEE0Uxzl_11OtA/edit?usp=sharing has a section at the bottom with some useful stuff to copy over.

We can start more sections under https://a-b-street.github.io/docs//user/index.html

Use minimal example json to show how to import .json files

It's worth doing but currently I get the following error message:

cargo run --bin import_traffic -- \
  --map=data/system/us/seattle/maps/montlake.bin \
  --input=minimal_scenario2.json
    Finished dev [unoptimized + debuginfo] target(s) in 0.13s
     Running `target/debug/import_traffic --map=data/system/us/seattle/maps/montlake.bin --input=minimal_scenario2.json`
import traffic demand data...
Read data/system/us/seattle/maps/montlake.bin (3)... 0.4303s
parse minimal_scenario2.json...
parse minimal_scenario2.json took 0.0001s
thread 'main' panicked at 'Couldn't read_json(minimal_scenario2.json): invalid type: floating point `10800`, expected i32 at line 7 column 30', /mnt/57982e2a-2874-4246-a6fe-115

Write-up 11th Ave NE -> Ravenna proposal

Create a user guide

A/B Street (and the other tools) have an overwhelming amount of features, many hard to discover and without adequate in-game explanation. Ideally the UI would be so clear that documentation wouldn't be needed, but until we get there, I think a "user guide" with lots of pictures would be helpful. I half-started one in a Google doc:

Each section of the guide could focus on "how to use the feature", and there could be an optional hidden-by-default section to explain in a little more technical detail how that thing works. For stop signs, for example, the user guide would explain how to edit them and the rules for people stopping/yielding. The technical would explain the rules for placing them automatically and emphasize that any traffic sign data from OSM isn't used yet.