Create a user guide

[dabreegster]

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.

[dabreegster]

I'm not sure what format the user guide should take. Adding to the existing mdbook in this repo seems heavy-handed; it's a bit tedious to resize/place screenshots appropriately there, and the high amount of screenshot churn will increase the git repo size. So tempted to dedicate a separate git repo for this, or even to start with a horrible massive Google doc and later turn into some kind of mdbook once the dust settles. Suggestions for other tools welcome. Maybe even the github wiki?

[michaelkirk]

An out of date guide seems like a bigger problem than an ugly guide, so my advice would be to optimize for writability with the "horrible massive Google doc" approach. And agreed that it could later be moved to another format if readability becomes a bigger concern than writability.

[Robinlovelace]

I'm happy to help out with this. I have found .md documents in GitHub great for writing and encouraging contributions, not least on the geocomputation with R book which as 50 contributors via GitHub, so think it could be done via github...

[Robinlovelace]

One option: we could even set-up a simple 'bookdown' auto-building book, as I recently did for the afrimapr project: https://github.com/afrimapr/afrimapr-book

[michaelkirk]

it's a bit tedious to resize/place screenshots appropriately there, and the high amount of screenshot churn will increase the git repo size

https://geocompr.robinlovelace.net looks like it has lots of nice diagrams. @Robinlovelace - any tips for an efficient image workflow?

[Robinlovelace]

Good question. 2 main options are save the screenshots into the git repo in a 'figures' folder or similar or, a lighter touch approach which keeps big binary image blobs out of nice clean repos which I use is to paste screenshots/gifs into GitHub issues which has the advantage of being super easy, just a matter of Ctl+C Ctl+V and then copying the image location, as shown in the GIF below generated by the open source software Peek : )

[dabreegster]

bookdown looks nice! The results are similar to mdbook, which we're using for the abst docs right now.

2 main options are save the screenshots into the git repo in a 'figures' folder or similar or, a lighter touch approach which keeps big binary image blobs out of nice clean repos

Where are the images stored if not in the repo? I think keeping them in git directly is fine; I would just start a new repo separate from the code.

[Robinlovelace]

Where are the images stored if not in the repo?

On GitHub, e.g.

![](https://user-images.githubusercontent.com/1825120/106162754-5bdf4880-6180-11eb-8c25-5ff6424b1237.gif)

Generates this

Not sure if that answers your question but it's a simple fix to avoid committing images to git repos.

[dabreegster]

I guess github does seemingly keep those images around forever. Is there a way to upload them and get the URL without using Issues? But it seems pretty desirable to actually have all the files stored in one place that's browseable/editable. Not clear that's possible/intended for the assets uploaded in issues.

I think the best format is to start a separate repo, abstreet-guide or abstreet-book or abstreet-docs, and use mdbook or similar. I'm actually not convinced mdbook is the best choice; I've hit problems like https://github.com/Michael-F-Bryan/mdbook-linkcheck/issues/40 trying to use tools to verify there are no broken links. I never took the time to shop around for other md implementations.

I guess a related question: does it make sense to start a github org for all of the abstreet related repositories? I could imagine a few others eventually appearing (like standalone code for turning OSM properties into shared-row, and maybe widgetry). I'll read about how github handles moving/renaming repos; there are so many places linking to github.com/dabreegster/abstreet that I don't want to break.

[Robinlovelace]

I think the best format is to start a separate repo, abstreet-guide or abstreet-book or abstreet-docs, and use mdbook or similar.

Agreed.

I guess a related question: does it make sense to start a github org for all of the abstreet related repositories?

My 10 cents: certainly!

[michaelkirk]

Transferring repos to an organization is straight forward and well tested: https://docs.github.com/en/github/administering-a-repository/transferring-a-repository

github.com/dabreegster/abstreet will continue to redirect to the new location indefinitely (both for people browsing to https://github.com/dabreegster/abstreet and for git remote urls)

[Robinlovelace]

github.com/dabreegster/abstreet will continue to redirect to the new location indefinitely (both for people browsing to https://github.com/dabreegster/abstreet and for git remote urls)

Works for sure. Fun fact: 2 days ago the osmextract, that Dustin kindly contributed to, moved from ITSLeeds to ropensci orgs after being peer reviewed by rOpenSci. See magic redirect here: https://github.com/ITSLeeds/osmextract

[dabreegster]

Alright, I started a github org, renamed the main repository to a-b-street/abstreet, and started this docs repo. Next steps towards making a user guide:

• possibly re-evaluate mdbook
• bring in some of the user guide drafted at the bottom of https://docs.google.com/document/d/1xb5VW09DgFeNxyMCVYg_uo_torqCBqEE0Uxzl_11OtA/edit?usp=sharing

[dabreegster]

Closing this issue because it got off-topic / grew in scope. I'm in the middle of reorganizing the docs/website completely. Anything I don't get to immediately, I'll file an issue to track it properly.