From b65629a37746d72af56019c208d8f156ca4523d9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Antoine=20Beaupr=C3=A9?= <anarcat@debian.org>
Date: Thu, 2 May 2019 10:09:05 -0400
Subject: [PATCH] explain better what cumin is and what it is for (and not for)

---
 tsa/howto/cumin.mdwn | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/tsa/howto/cumin.mdwn b/tsa/howto/cumin.mdwn
index bc179c45..25d70640 100644
--- a/tsa/howto/cumin.mdwn
+++ b/tsa/howto/cumin.mdwn
@@ -1,7 +1,17 @@
 # Cumin
 
-You can use [Cumin][] to operate arbitrary shell commands on Puppet
-hosts or a subset of hosts.
+[Cumin][] is a tool to operate arbitrary shell commands on [[Puppet]]
+hosts that match a certain criteria. It can match classes, facts and
+other things stored in the PuppetDB.
+
+It is useful to do adhoc or emergency changes on a bunch of machines
+at once. It is especially useful to run Puppet itself on multiple
+machines at once to do progressive deployments.
+
+It should *not* be used as a replacement for Puppet itself: most
+configuration on server should *not* be done manually and should
+instead be done in Puppet manifests so they can be reproduced and
+documented.
 
  [Cumin]: https://doc.wikimedia.org/cumin/master/introduction.html
 
-- 
GitLab