headless: Improve documentation

headless/README.md

Index: headless/README.md
diff --git a/headless/README.md b/headless/README.md
index 9e98dae1d36f06aed2a9491068ab342c91700d3c..bcb2bc035b4f18cb7b3832da4ae4064084d2f526 100644
--- a/headless/README.md
+++ b/headless/README.md
@@ -1,17 +1,34 @@
 # Headless Chromium
 
-Headless Chromium is a library for running Chromium in a headless/server
-environment. Expected use cases include loading web pages, extracting metadata
-(e.g., the DOM) and generating bitmaps from page contents -- using all the
-modern web platform features provided by Chromium and Blink.
+Headless Chromium allows running Chromium in a headless/server environment.
+Expected use cases include loading web pages, extracting metadata (e.g., the
+DOM) and generating bitmaps from page contents -- using all the modern web
+platform features provided by Chromium and Blink.
 
-See the [architecture design doc](https://docs.google.com/document/d/11zIkKkLBocofGgoTeeyibB2TZ_k7nR78v7kNelCatUE)
-for more information.
+There are two ways to use Headless Chromium:
 
-## Headless shell
+## Usage via the DevTools remote debugging protocol
 
-The headless shell is a sample application which demonstrates the use of the
-headless API. To run it, first initialize a headless build configuration:
+1. Start a normal Chrome binary with the `--headless` command line flag
+(Linux-only for now):
+
+```
+$ chrome --headless --remote-debugging-port=9222 https://chromium.org

[Eric Seckler, 2016/12/23 10:51:46]

should we mention --disable-gpu?

[Sami, 2016/12/23 10:59:43]

Good point, done!

+```
+
+2. Navigate to `http://localhost:9222` in another browser to open the
+[DevTools](https://developer.chrome.com/devtools) interface or use a tool such
+as [Selenium](http://www.seleniumhq.org/) to drive the headless browser.
+
+## Usage as a C++ library
+
+Headless Chromium can be built as a library for embedding into a C++
+application. This approach is otherwise similar to controlling the browser over
+a DevTools connection, but it provides more customization points, e.g., for
+networking and [mojo services](https://docs.google.com/document/d/1Fr6_DJH6OK9rG3-ibMvRPTNnHsAXPk0VzxxiuJDSK3M/edit#heading=h.qh0udvlk963d).
+
+Headless Shell is a sample application which demonstrates the use of the
+headless C++ API. To run it, first initialize a headless build configuration:
 
 ```
 $ mkdir -p out/Debug
@@ -25,8 +42,7 @@ Then build the shell:
 $ ninja -C out/Debug headless_shell
 ```
 
-After the build completes, the headless shell can be run with the following
-command:
+After the build completes, Headless Shell can be run with the following command:
 
 ```
 $ out/Debug/headless_shell https://www.google.com
@@ -39,7 +55,7 @@ shell, start it with an argument specifying the debugging port:
 $ out/Debug/headless_shell --remote-debugging-port=9222 https://youtube.com
 ```
 
-Then navigate to `http://127.0.0.1:9222` with your browser.
+Then navigate to `http://localhost:9222` with your browser.
 
 ## Embedder API
 
@@ -67,7 +83,10 @@ web pages. Its main classes are:
   See the [client API documentation](https://docs.google.com/document/d/1rlqcp8nk-ZQvldNJWdbaMbwfDbJoOXvahPCDoPGOwhQ/edit#)
   for more information.
 
-## Documentation
+## Resources and Documentation
+
+Mailing list: [headless-dev@chromium.org](https://groups.google.com/a/chromium.org/forum/#!forum/headless-dev)
+Bug tracker: [Proj=Headless](https://bugs.chromium.org/p/chromium/issues/list?can=2&q=Proj%3DHeadless)
 
 * [Runtime headless mode for Chrome](https://docs.google.com/document/d/1aIJUzQr3eougZQp90bp4mqGr5gY6hdUice8UPa-Ys90/edit#)
 * [Virtual Time in Blink](https://docs.google.com/document/d/1y9kdt_zezt7pbey6uzvt1dgklwc1ob_vy4nzo1zbqmo/edit#heading=h.tn3gd1y9ifml)
@@ -78,3 +97,4 @@ web pages. Its main classes are:
 * [Controlling BeginFrame through DevTools](https://docs.google.com/document/d/1LVMYDkfjrrX9PNkrD8pJH5-Np_XUTQHIuJ8IEOirQH4/edit?ts=57d96dbd#heading=h.ndv831lc9uf0)
 * [Viewport bounds and scale for screenshots](https://docs.google.com/document/d/1VTcYz4q_x0f1O5IVrvRX4u1DVd_K34IVUl1VULLTCWw/edit#heading=h.ndv831lc9uf0)
 * [BlinkOn 6 presentation slides](https://docs.google.com/presentation/d/1gqK9F4lGAY3TZudAtdcxzMQNEE7PcuQrGu83No3l0lw/edit#slide=id.p)
+* [Architecture design doc](https://docs.google.com/document/d/11zIkKkLBocofGgoTeeyibB2TZ_k7nR78v7kNelCatUE)