What makes a good puzzle?

I made a Godot addon for building puzzle dependency charts.

It helps with designing adventurer game puzzles and ensuring there are no dead ends that make progression impossible.

Puzzle dependency charts also help highlight the breadth of puzzles and show where a game is too linear or too overwhelming.

Having no dead ends and multiple options are things that make a good puzzle game but what about the puzzles themselves?

I have two questions I ask myself when I've thought of a potential puzzle:

1. How would a player know to do that?

   The first question makes sure the player isn't stumbling around in the dark.

   There should be enough knowledge provided in the game to hypothesise about the solution.

   Telegraphing can be done in a few ways, from subtle character dialogue (or even obvious character dialogue if it fits the style of the game) through to environmental hints.

   One example of good environmental hinting can be found in Zelda: Link's Awakening.

   There is a hidden room in the Key Cavern that can only be accessed by using bombs against a specific wall.

   Usually walls that are susceptible to bombs have special cracks in them but to help the player discover this particular wall they are given an extra hint - a giant arrow on the ground drawn with tiles.

   It's not overly subtle but it also doesn't explicitly spell it out either.

2. Does the solution make sense once you know the answer?

   This second question is for after the solution is found.

   If a player randomly stumbles on the answer but are still confused as to why that worked then the puzzle is probably either too abstract, relies on overly specific knowledge, or is just a bad idea in general.

   That doesn't mean solutions have to be boring.

   It just means that the game needs to be internally consistent and the puzzles need to abide by the games own rules.

   There's a puzzle in Full Throttle that involves a chain that when pulled opens a gate. As soon as you let go, however, the gate closes again.

   You have a padlock that you might initially think should be used on the chain to keep the gate open but the solution to the puzzle is to padlock the gate shut so that the chain stays in place.

   You can then climb the chain to get over the wall.

   The solution is surprising but it does make sense.

Unfortunately, as the puzzle designer, you can never truly know if you've hit the mark until you put your puzzles in front of real players.

You'll know you've found the perfect balance when the player gets a sense of being clever when they figure it out.