Extend plugin documentation

* Add section to main README
* Add introduction to plugins-specific README

README.md

@@ -259,6 +259,19 @@ kubectl create -f scope-app-svc.yaml # Only if you want to run Scope in Standalo
 kubectl create -f scope-probe-ds.yaml
 ```
 
+## <a name="probe_plugins"></a>Scope Probe Plugins
+
+Scope allows you to create plugins generating custom
+metrics. Those metrics will be displayed in the Scope UI.
+
+Here is an annotated screenshot of Scope while executing a plugin which extracts
+incoming HTTP request rates of your application without instrumenting it.
+
+<img src="imgs/plugin.png" width="400" alt="Scope Probe plugin screenshot" align="center">
+
+
+You can read more about Scope Probe plugins and find some examples
+[here](https://github.com/weaveworks/scope/tree/master/examples/plugins).
 
 ## <a name="developing"></a>Developing
 

examples/plugins/README.md

@@ -1,4 +1,24 @@
-# Scope Plugins
+# Scope Probe Plugins
+
+Scope probe plugins let you insert your own custom metrics into Scope and get them displayed in the UI.
+
+You can find some examples at the
+[the example plugins](https://github.com/weaveworks/scope/tree/master/examples/plugins)
+directory. We currently provide two examples:
+* A
+  [Python plugin](https://github.com/weaveworks/scope/tree/master/examples/plugins/http-requests)
+  using [bcc](http://iovisor.github.io/bcc/) to extract incoming HTTP request
+  rates per process, without any application-level instrumentation requirements.
+* A
+  [Go plugin](https://github.com/weaveworks/scope/tree/master/examples/plugins/iovisor),
+  using [iostat](https://en.wikipedia.org/wiki/Iostat) to provide host-level CPU IO wait
+  metrics.
+
+The example plugins can be run by calling `make` in their directory.
+This will build the plugin, and immediately run it in the foreground.
+To run the plugin in the background, see the `Makefile` for examples
+of the `docker run ...` command.
+
 
 ## <a id="protocol"></a>Protocol
 
@@ -13,8 +33,6 @@ reports from it via `GET /report`.
 
 All plugin endpoints are expected to respond within 500ms, and respond in the JSON format.
 
-For more information see [the example plugins.](https://github.com/weaveworks/scope/tree/master/example/plugins)
-
 ### <a id="report"></a>Report
 
 When the scope probe discovers a new plugin unix socket it will begin