Improve explanation of miscgroups

1 files changed, 36 insertions, 13 deletions

diff --git a/API.md b/API.md
index 9db38bf..58882a6 100644
--- a/API.md
+++ b/API.md
@@ -258,32 +258,55 @@ Add a list of groups you think are notable enough to be mentioned in the
 is intended to give a quick rundown of misc. groups which don't fit
 to other factoids, yet they are still somewhat relevant to gameplay.
 
-`groupnames` is a table of group names.
-
-Groups which are used for crafting or in the `connects_to` field of item
-definitions are already automatically added to this factoid, so you can
-omit those (but no harm is done if you do it anyway).
+`groupnames` is a table of group names you wish to add.
 
+#### What groups should be added
 What is “notable” is subjective, but there are some guidelines:
 
-You should add groups with this function if this group is somehow important
-for interaction, interesting for the player and not already covered by the
-other factoids.
+Do add a group if:
+
+* It is used in an ABM
+* It is somehow used for a custom interaction with another item
+* It is simple enough for the player to know an item is member of this group
+* You want to refer to this group in help texts
+* The “don'ts” below don't apply
 
 Note that most groups are probably already covered elsewhere, so you
 probably only need to add a few groups here.
 
 Do not add a group if:
 
-* It is *only* used for crafting purposes (this is already covered)
-* It *only* appears in `connect_to` definitions of nodes (this is covered, too)
-* The group is a mining or damage group (this is covered, too)
-* The group is only used internally
-* The group is uninteresting for the player
+* It is *only* used for crafting purposes
+* It *only* appears in `connect_to` definitions of nodes
+* The group is *only* a mining or damage group
+* The group membership itself requires an explanation (consider writing a
+  factoid instead)
+* The group has no gameplay relevance
 * A factoid covering this group already exists
 * Writing a factoid would be more useful
 * Group rating is important to gameplay (consider writing a factoid instead)
 
+Groups which are used for crafting or in the `connects_to` field of item
+definitions are already automatically added to this factoid.
+
+##### Examples for good additions
+
+* `book` in Minetest Game: Members of this group can be placed in bookshelves,
+  so this group meets the “custom interaction” criterion
+* `water` in Minetest Game: Used for water nodes with some ABM.
+* `sand` in Minetest Game: Used for the cactus growth ABM, but also crafting.
+  Since it is not *only* used for crafting, it is OK to be added
+
+##### Examples for bad additions
+
+* `stick`: in Minetest Game: This group appears in many crafting recipes and
+  has no other use. It is already added automatically
+* A group in which members turn into obsidian when they touch water (ABM):
+  This group is not trivial and should be introduced in a factoid instead
+* `cracky` in Min
+* `dig_immediate`: This group is already covered by the default factoids of this
+  mod
+
 ## Dependencies
 If you only add the custom fields to your items, you do *not* need to depend
 on this mod. If you use anything else from this mod (e.g. a function), you