Review tut-charms

src/en/authors-charm-metadata.md

@@ -57,7 +57,7 @@ fields:
   sequence format if there are multiple people.
 
   - `tags`: A list of descriptive tags used for organisation purposes in the
-    Charm Store. Choose from among the following:
+    Charm Store. Choose from among the following common words:
 
      - analytics
      - big_data

src/en/charms-deploying-advanced.md

@@ -118,7 +118,7 @@ Assuming a LXD cluster cloud named 'lxd-cluster' exists and has a node called
 juju bootstrap lxd-cluster --to node3
 ```
 
-### deploy --to
+### `deploy --to` command
 
 To deploy the 'haproxy' application to machine '2' we would do this:
 
@@ -170,7 +170,7 @@ and added to the node. For example:
 juju deploy mariadb-k8s --to kubernetes.io/hostname=somehost
 ```
 
-### add-unit --to
+### `add-unit --to` command
 
 To add a unit of 'rabbitmq-server' to machine '1':
 

src/en/charms-working-with-units.md

@@ -1,33 +1,10 @@
 Title: Working with units  
-TODO:  Convert into a tutorial
 
 # Working with units
 
-Each node that Juju manages is referred to as a "unit". Generally speaking,
-when using Juju you interact with the applications at the application level. 
-There are times when working directly with units is useful though, particularly
-for debugging purposes. Juju provides a few different commands to make this
-easier.
 
 
-## The juju ssh command
-
-The `juju ssh` command will connect you, via SSH, into a target unit. For
-example:
-
-```bash
-juju ssh mysql/3
-```
-
-This will start an SSH session on the 3rd mysql unit. This is useful for
-investigating things that happen on a unit, checking resources or viewing
-system logs.
-
-It is possible to run commands via `juju ssh`, for example, `juju ssh 1 uname
--a` will run the uname command on node one. This works for simple commands,
-however for more complex commands we recommend using `juju run` instead.
-
-See also the `juju help ssh` command for more information.
+## Connecting to units via SSH
 
 
 ## The juju scp command
@@ -66,45 +43,64 @@ juju scp -m testing foo.txt apache2/1:
 
 !!! Note:
     Juju cannot transfer files between two remote units because it uses public
-    key authentication exclusively and the native (OpenSSH) `scp` command disables
-    agent forwarding by default. Either the destination or the source must be local
-    (Juju client).
+    key authentication exclusively and the native (OpenSSH) `scp` command
+    disables agent forwarding by default. Either the destination or the source
+    must be local (Juju client).
 
 For more information, run the `juju help scp` command.
 
 
-## The juju run command
+## ???
 
-The `juju run` command can be used by devops or scripts to inspect or do work
-on applications, units, or machines. Commands for applications or units are
-executed in a hook context. Charm authors can use the run command to develop 
-and debug scripts that run in hooks.
+The `run` command can be used to inspect or perform work on machines by
+targeting applications, units, or actual machines. The command operates on a
+per-model basis.
+
+!!! Note:
+    Only users with 'admin' model access can use the `run` command.
 
-For example, to run uname on every instance:
+For example, consider the Linux `uname` command in the below scenarios.
+
+ - To target all machines in a model the `--all` option is used:
 
 ```bash
-juju run "uname -a" --all
+juju run --all uname
 ```
 
-Or to run uptime on some instances:
+ - To target all units of specific applications the `--application` option is
+   used:
 
 ```bash
-juju run "uptime" --machine=2
-juju run "uptime" --application=mysql
+juju run --application=mysql uname
 ```
 
-!!! Note: 
-    When using `juju run` with the `--application` option, keep in mind
-    that whichever command you pass will run on *every unit* of that application.
-    When using `juju run` with the `--machine` option, the command is run as the
-    `root` user on the remote machine.
+ - To target a single unit of a specific application the `--unit` option is
+   used:
 
-When used in combination with certain applications you can script certain tasks.
-For instance, in the 'hadoop' charm you can use `juju run` to initiate a
-terasort:
+```bash
+juju run --unit=mysql/0,mysql/1 uname 
+```
+
+ - To target specific machines the `--machines` option is used (command is run
+   as the 'root' user on the target machines).
 
 ```bash
-juju run --unit hadoop-master/0 "sudo -u hdfs /usr/lib/hadoop/terasort.sh"
+juju run --machine=0,2 uname 
 ```
 
-For more information see the `juju help run` command.
+To pass options or arguments with the command precede it with '--'. For
+example:
+
+ ```bash
+juju run --all -- hostname -f
+ ```
+
+!!! Positive "Pro tip":
+    Commands for applications or units are executed in a hook context. Charm
+    authors can therefore use the `run` command to develop and debug scripts
+    that run in hooks.
+
+
+<!-- LINKS -->
+
+

src/en/machine-auth.md

@@ -41,6 +41,12 @@ For example, to connect to a machine with an id of '0':
 juju ssh 0
 ```
 
+You can also connect to a machine by specifying a unit:
+
+```bash
+juju ssh nginx/3
+```
+
 An interactive pseudo-terminal (pty) is enabled by default. For the OpenSSH
 client, this corresponds to the `-t` option ("force pseudo-terminal
 allocation").

src/en/reference-bundle.md

@@ -74,9 +74,9 @@ series: bionic
 #
 # tags:
 #
-# Sets descriptive tags. A tag is used for organisational purposes in the
-# Charm Store. See https://docs.jujucharms.com/authors-charm-metadata for the
-# list of valid tags.
+# Sets descriptive tags. A tag is user-defined. It is used for organisational
+# purposes in the Charm Store. See
+# https://docs.jujucharms.com/authors-charm-metadata for examples.
 #
 
 tags: [monitoring]