moth

writing-puzzles.md

 1How to create puzzle categories
 2===============================
 3
 4The contest has multiple "puzzle" categories.  Each category contains a
 5collection of thematically-related puzzles with increasing point
 6values.  This document will guide you through the process of creating a
 7new category.  It's up to you to make challenging puzzles, though :)
 8
 9Since Unix commands are plain text, I'll be using the Unix commands to
10illustrate steps.  These are simple commands that should be easy to
11translate to a GUI.
12
13
14Step 1: Establish a progression
15-------------------------------
16
17Before you do anything else, you should sit down with a pen and paper,
18and plan out how you'd like contestants to progress through your
19category.  This contest framework is set up to encourage a linear
20progression through puzzles, while still allowing contestants to skip
21over things they get stuck on.
22
23The net-re category, for instance, features full tutorial pages with
24simple "end of chapter" type questions for point values 1-8.  Point
25values 10-99 apply the skills learned in the tutorial against
26increasingly challenging problems, point values 100-999 increasingly
27approach real-world challenges which use the skills, and point values
281000+ are either culled or inspired by actual net-re tasks performed by
29experts in the field.
30
31The crypto category uses the previous answers key as part of the
32solution process for each point value.
33
34Ideally, your category will work standalone for novices, while allowing
35experts to quickly answer the training questions and progress to real
36challenges.  Remember that some events don't have a class portion, and
37even the ones that do have students who prefer to spend the contest time
38reviewing the exact same problems they did in the class.
39
40Remember, it's easy to make incredibly challenging puzzles, and you will
41probably have a lot of ideas about how to do this.  What's harder is to
42make simple puzzles that teach.  It can be helpful to imagine a student
43with a basic skill set.  Write your first puzzle for this student to
44introduce them to the topic and get them thinking about things you
45believe are important.  Guide that student through your tutorial
46puzzles, until they emerge ready to tackle some non-tutorial problems.
47As they gain confidence, keep them on their toes with new challenges.
48Remember to only introduce one new concept for each puzzle!
49
50Past a certain point, feel free to throw in the killer tricky puzzles
51you're just dying to create!
52
53
54
55Step 2: Establish point values
56------------------------------
57
58Each of your steps needs a point value.  Each point value must be
59unique: you may not have two 5-point puzzles.
60
61Point values should roughly reflect how difficult a problem is to solve.
62It's not terribly important that a 200-point puzzle be ten times harder
63than a 20-point puzzle, but it is crucial that a 25-point puzzle be
64roughly as difficult as a 20-point puzzle.  Poorly-weighted puzzles has
65been the main reason students lose interest.
66
67
68
69Step 3: Set up your puzzle structure
70------------------------------------
71
72The best way to get puzzles to me is in a zip file of an entire
73directory.  Let's say you are going to create a "sandwich" category.
74Your first step will be to make a "sandwich" directory somewhere.
75
76    $ mkdir sandwich
77    $ cd sandwich
78    $
79
80Within your category directory, create subdirectories for each point
81value puzzle.  In the "sandwich" category we have only 5, 10, and
82100-point puzzles.
83
84    $ mkdir 5 10 100
85    $
86
87
88Step 4: Write puzzles
89---------------------
90
91Now that your skeleton is set up, you can begin to fill it in.
92Check the `example-puzzles` directory for examples of how to format puzzles,
93and how to use the Python Puzzle object for dynamically-generated puzzles.