groups: add docs

docs/content/dependencies.md

@@ -142,3 +142,78 @@ would all work like [the param example in the getting started guide]({{< ref
 "getting-started.md" >}}#params). We're not quite there yet, but keep an eye
 out!
 {{< /note >}}
+
+## Grouping
+
+There can be some scenarios where a group of tasks are not explicitly dependent
+on each other but also cannot be run in parallel. A good example of this is
+package management tools like
+[apk](http://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management) or
+[apt](https://wiki.debian.org/Apt). As an example, let's look at this file which
+installs three packages:
+
+```hcl
+task "install-tree" {
+  check = "dpkg -s tree >/dev/null 2>&1"
+  apply = "apt-get install -y tree"
+}
+
+task "install-jq" {
+  check = "dpkg -s jq >/dev/null 2>&1"
+  apply = "apt-get install -y jq"
+}
+
+task "install-build-essential" {
+  check = "dpkg -s build-essential >/dev/null 2>&1"
+  apply = "apt-get install -y build-essential"
+}
+```
+
+Here is what the corresponding graph looks like:
+
+{{< figure src="/images/dependencies/without-groups.png" caption="The graph output of the above module. Converge will attempt to run each task in parallel." >}}
+
+If you were to execute apply against this graph, you would end up with errors
+that look something like this:
+
+```shell
+E: Could not get lock /var/lib/apt/lists/lock - open (11: Resource temporarily unavailable)
+E: Unable to lock directory /var/lib/apt/lists/
+```
+
+This is because multiple `apt-get` commands cannot be run at the same time.
+
+You could certainly use `depends` to chain these tasks together but this is
+tedious and error prone. Luckily, Converge supports `groups` which makes this
+much easier. We can add a named group to each task and Converge will modify the
+graph so that these tasks are not run in parallel.
+
+```hcl
+task "install-tree" {
+  check = "dpkg -s tree >/dev/null 2>&1"
+  apply = "apt-get install -y tree"
+  group = "apt"
+}
+
+task "install-jq" {
+  check = "dpkg -s jq >/dev/null 2>&1"
+  apply = "apt-get install -y jq"
+  group = "apt"
+}
+
+task "install-build-essential" {
+  check = "dpkg -s build-essential >/dev/null 2>&1"
+  apply = "apt-get install -y build-essential"
+  group = "apt"
+}
+```
+
+And the corresponding graph:
+
+{{< figure src="/images/dependencies/with-groups.png" caption="The graph output of the above module. The tasks in the group will not run in parallel." >}}
+
+{{< note title="Future Improvements" >}}
+In this example, we are installing packages by calling `apt-get` in Converge
+tasks. We plan to build higher-level resources to handle package management that
+will handle these details for you.
+{{< /note >}}