word-smith XOS Guide
Change-Id: Ia048ddc41065de0eca3d613e1c6d62a66c2a52eb
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 353863f..adb2f98 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -16,6 +16,7 @@
* [Core Models](core_models.md)
* [Security Policies](security_policies.md)
* [Tutorial](tutorials/basic_synchronizer.md)
+ * [XOS Shell (xossh)](dev/xossh.md)
* [Platform Services](platform.md)
* [Kubernetes](kubernetes/kubernetes-service.md)
* [OpenStack](openstack/openstack-service.md)
diff --git a/docs/dev/xossh.md b/docs/dev/xossh.md
index 23fbc01..d6c2d98 100644
--- a/docs/dev/xossh.md
+++ b/docs/dev/xossh.md
@@ -1,15 +1,25 @@
# XOSSH
-XOSSH is a cli tool that lets you perfom operations on the data model.
-To set it up, deploy the [`xossh`](../../charts/xossh.md) chart:
+XOSSH is a shell (CLI tool) that lets you directly operate on the XOS
+data model. To use XOSSH, first deploy it using the `xossh` helm
+chart:
-To connect to the `xossh` container, you can use this command (from the `helm-chart` folder):
+```shell
+cd helm-charts
+helm install xos-tools/xossh -n xossh
+```
+
+To connect to the `xossh` container, you can use this command (from
+the `helm-chart` directory):
+
```bash
bash xos-tools/xossh/xossh-attach.sh
```
-It will connect to the `grpc` APIs exposed by `xos-core` and start a `python` shell.
-Once started you should see this on your console:
+This will connect to the `grpc` APIs exposed by `xos-core` and start a
+`python` shell.
+
+Once started, you should see this on your console:
```bash
__ __ ____ _____ _____ _ _