start a guided tour

1 files changed, 57 insertions, 0 deletions

diff --git a/tour.md b/tour.md
new file mode 100644
index 0000000..0154e4b
--- /dev/null
+++ b/tour.md
@@ -0,0 +1,57 @@
+# A guided tour of Teliva
+
+Teliva is intended to be a safe environment for running shareable little
+text-mode Lua apps that are easy to modify. Apps aren't sandboxed yet, but I'm
+working on that.
+
+This page is an in-progress guided tour through [Teliva's Readme](https://github.com/akkartik/teliva#readme)
+and Lua's reference documentation. We'll start out really slow and gradually
+accelerate.
+
+_Prerequisites_
+
+You will need the following to build Teliva:
+
+* A non-mobile computer running some sort of Unix variant. Teliva has been
+  tested on Linux, OpenBSD and Mac OS X. (Other BSD variants and Windows
+  Subsystem for Linux should require minor changes at most. Please [contact me](http://akkartik.name/contact)
+  if you run into issues running Teliva on your computer.)
+* [Git](https://git-scm.com).
+* A working C toolchain.
+* Some fluency in typing commands at the terminal and interpreting their
+  output.
+
+## Task 1: getting started
+
+Read the first question in [the Readme](https://github.com/akkartik/teliva/blob/main/README.md)
+Try running the commands to download and build Teliva. If you have any trouble
+at this point, don't waste _any_ time thinking about it. Just [get in
+touch](http://akkartik.name/contact).
+
+Run the simplest example app:
+
+```sh
+src/teliva counter.tlv
+```
+
+Can you figure out what this app does, what you can do with it? There's a
+number on screen. Hit `enter`. The number increments by 1. Hit `ctrl-x` to
+exit (press `ctrl` and `x` on your keyboard at the same time).
+
+Try editing the app by hitting `ctrl-e`. You see a "big picture" view of the
+app. Can you figure out how to modify this app to increment by 2 each time you
+hit `enter`? Don't be afraid to experiment. The menu at the bottom always
+shows the hotkeys available to you at any point in time. Don't worry,
+everything you do can be undone.
+
+Check out some of the short sections from [the Lua book](https://www.lua.org/pil/contents.html)
+that might be useful at this point: [assignment](https://www.lua.org/pil/4.1.html); [what you can do with numbers](https://www.lua.org/pil/3.1.html).
+
+(Buy the Lua book to support the creators of Lua. Teliva is a tiny molehill on
+the mountain of awesome that is Lua.)
+
+Once you make a change, can you figure out how to restart the app with your
+changes?
+
+After you've made a change, try exiting Teliva and restarting it with the same
+app. Do you still see your changes?