@@ -37,8 +37,9 @@ jobs:
 
       - restore_cache:
           key: *cache_key
+
       - run: bazel info release
-      - run: bazel run @yarn//:yarn
+      - run: bazel run --config=ci @yarn//:yarn
       - run: bazel build --config=ci ...
 
       - save_cache:
 
@@ -4,41 +4,44 @@
 
 **This is experimental! There may be breaking changes.**
 
-This is part of the ABC project. See http://g.co/ng/abc for an overview.
+This is part of the ABC project. The overall goal is to make it possible to
+develop Angular applications the same way we do at Google.
+See http://g.co/ng/abc for an overview.
 
-See the documentation in the wiki of this repository to install the
-necessary dependencies and understand how this works.
+You can read the documentation in the wiki of this repository to understand how
+this works.
 
 Follow https://github.com/angular/angular/issues/19058 for updates.
 
 ## Try it
 
+First, we install packages as usual. However, to get the same version of node
+and yarn as co-workers and our continuous integration, let's have Bazel run the
+package manager using a pinned version it manages.
+
 ```bash
-# Install packages, uses hermetic version of node and yarn
 $ bazel run @yarn//:yarn
-# Start up the devserver in watch mode
-$ ./node_modules/.bin/ibazel run src:devserver
-# Open the URL printed on your terminal.
-# Make changes to sources, observe the development round-trip time
 ```
 
-Look at the dependency graph:
+Next we'll run the development server. The `ibazel` command is a "watch mode"
+for Bazel, which means it will watch any files that are inputs to the devserver,
+and when they change it will ask Bazel to re-build them. The devserver stays
+running, and when the re-build is finished, it will trigger the Livereload in
+the browser.
 
 ```bash
-$ bazel query --output=graph ... | dot -Tpng > graph.png
+$ ./node_modules/.bin/ibazel run src:devserver
 ```
 
-![bazel query](graph.png)
+This command prints a URL on the terminal. Open that page to see the demo app
+running. Now you can edit one of the source files (`src/lib/file.ts` is an easy
+one to understand and see the effect). As soon as you save a change, the app
+should refresh in the browser with the new content. Our intent is that this time
+is less than two seconds, even for a large application.
 
-
-## Still missing
+## Coming soon
 
 Karma testing rules are in-progress, should be available Q4 2017
 
 Production bundling with https://github.com/bazelbuild/rules_closure/ is
 underway, should be available Q4 2017
-
-## Notes
-
-- we use Bazel to run Yarn simply to be sure we get the same versions of Node and Yarn as CI and co-workers (hermeticity FTW). You could use NPM instead
-- a `postinstall` task in the `package.json` prepares the `node_modules` directory by running the Angular compiler on third_party libraries (such as Angular itself) since these do not ship with generated code (eg. `ngfactory`s)