diff --git a/tokio-console/README.md b/tokio-console/README.md
index a84572a78..12a7d466a 100644
--- a/tokio-console/README.md
+++ b/tokio-console/README.md
@@ -97,30 +97,87 @@ tokio-console http://my.instrumented.application.local:6669
See [here][cli-ref] for a complete list of all command-line arguments.
+Tokio Console has a numnber of different views:
+* [Tasks List](#tasks-list)
+* [Task Details](#task-details)
+* [Resources List](#resources-list)
+* [Resource Details](#resource-details)
+
+### Tasks List
+
When the console CLI is launched, it displays a list of all [asynchronous tasks]
in the program:
+Tasks are displayed in a table.
+
+* `Warn` - The number of warnings active for the task.
+* `ID` - The ID of the task. This is the same as the value returned by the unstable [`tokio::task::Id`](https://docs.rs/tokio/latest/tokio/task/struct.Id.html) API (see documentation for details).
+* `State` - The state of the task.
+ * `RUNNING`/▶ - Task is currently being polled.
+ * `IDLE`/⏸ - Task is waiting on some resource.
+ * `SCHED`/⏫ - Task is scheduled (it has been woken but not yet polled).
+ * `DONE`/⏹ - Task has completed.
+* `Name` - The name of the task, which can be set when spawning a task using the unstable [`tokio::task::Builder::name()`](https://docs.rs/tokio/latest/tokio/task/struct.Builder.html#method.name) API.
+* `Total` - Duration the task has been alive (sum of Busy, Sched, and Idle).
+* `Busy` - Total duration for which the task has been actively executing.
+* `Sched` - Total duration for which the task has been scheduled to be polled by the runtime.
+* `Idle` - Total duration for which the task has been idle (waiting to be woken).
+* `Polls` - Number of times the task has been polled.
+* `Target` - The target of the span used to record the task.
+ * `tokio::task` - Async task.
+ * `tokio::task::blocking` - A blocking task (created with [tokio::task::spawn_blocking](https://docs.rs/tokio/latest/tokio/task/fn.spawn_blocking.html)).
+* `Location` - The source code location where the task was spawned from.
+* `Fields` - Additional fields on the task span.
+ * `kind` - may be `task` (for async tasks) or `blocking` (for blocking tasks).
+ * `fn` - function signature for blocking tasks. Async tasks don't record this field, as it is generally very large when using `async`/`await`.
+
Using the ↑ and ↓ arrow keys, an individual task can be highlighted.
Pressingenter while a task is highlighted displays details about that
-task:
+task.
+
+### Task Details
+
+This view shows details about a specific task:
+The task details view includes percentiles and a visual histogram of the polling (busy) times
+and scheduled times.
+
Pressing the escape key returns to the task list.
+### Resources List
+
The r key switches from the list of tasks to a list of [resources],
such as synchronization primitives, I/O resources, et cetera:
+Resources are displayed in a table similar to the task list.
+
+* `ID` - The ID of the resource. This is a display ID as there is no internal resource ID to reference.
+* `Parent` - The ID of the parent resource if it exists.
+* `Kind` - The resource kind, this is a high level grouping of resources.
+ * `Sync` - Synchronization resources from [`tokio::sync`](https://docs.rs/tokio/latest/tokio/sync/index.html) such as [`Mutex`](https://docs.rs/tokio/latest/tokio/sync/struct.Mutex.html).
+ * `Timer` - Timer resources from [`tokio::time`](https://docs.rs/tokio/latest/tokio/time/index.html) such as [`Sleep`](https://docs.rs/tokio/latest/tokio/time/struct.Sleep.html).
+* `Total` - Total duration that this resource has been alive.
+* `Target` - The module path of the resource type.
+* `Type` - The specific type of the resource, possible values depend on the resources instrumented in Tokio, which may vary between versions.
+* `Vis` - The visibility of the resource.
+ * `INT`/🔒 - Internal, this resource is only used by other resources.
+ * `PUB`/✅ - Public, available in the public Tokio API.
+* `Location` - The source code location where the resource was created.
+* `Attributes` - Additional resource-dependent attributes, for example a resource of type `Sleep` record the `duration` of the sleep.
Pressing the t key switches the view back to the task list.
Like the task list view, the resource list view can be navigated using the
↑ and ↓ arrow keys. Pressing enter
-while a resource is highlighted displays details about that resource:
+while a resource is highlighted displays details about that resource.
+
+### Resource Details
@@ -130,6 +187,18 @@ a large number of tasks, such as this private `tokio::sync::batch_semaphore::Sem
+The resource details view includes a table of async ops belonging to the resource.
+
+* `ID` - The ID of the async op. This is a display ID similar to those recorded for resources.
+* `Parent` - The ID of the parent async op, if it exists.
+* `Task` - The ID and name of the task which performed this async op.
+* `Source` - The method where the async op is being called from.
+* `Total` - Total duration for which the async op has been alive (sum of Busy and Idle, as an async op has no scheduled state).
+* `Busy` - Total duration for which the async op has been busy (its future is actively being polled).
+* `Idle` - Total duration for which the async op has been idle (the future exists but is not being polled).
+* `Polls` - Number of times the async op has been polled.
+* `Attributes` - Additional attributes from the async op. These will vary based on the type of the async op.
+
Like the task details view, pressing the escape key while viewing a resource's details
returns to the resource list.