diff --git a/projects/nibble-dice-tracker.tal b/projects/nibble-dice-tracker.tal
index c52c060..b9c53d3 100644
--- a/projects/nibble-dice-tracker.tal
+++ b/projects/nibble-dice-tracker.tal
@@ -1,6 +1,41 @@
 ( nibble-dice-tracker.tal )
 ( 3-channel music tracker based on the nibble dice described by maleza )
 ( sejo cc0 12021 )
+(
+# controls
+
+* Arrow key up, or 'k' : move cursor to previous byte
+* Arrow key down, or 'j': move cursor to next byte
+* Arrow key left, or 'h': move cursor to previous nibble
+* Arrow key right, or 'l': move cursor to next nibble
+* 'Ctrl' or '+': increment nibble
+* 'Alt' or '-': decrement nibble
+
+# meaning of dice columns
+
+two columns per device, for a total of three devices
+
+# first column
+
+* period -  1 byte  - how many frames have to happen to trigger a beat. if 0, the device is off
+* pattern - 8 bits - each bit indicates if a note has to be played or not in that beat. bit 0  corresponds to beat 0, bit 1 to beat 1, and so on.
+* beatcount - 2 nibbles  - definition of the beat count behavior. low nibble: how many beats happen in a cycle; if 0, there are no beats. high nibble: beat offset; starting value for the beat count. e.g. if high nibble is 2, and low nibble is 4, the beat count will repeat as 2, 3, 4, 5
+* adsr - 2 bytes  - envelope values, as described by the audio device reference
+* volume - 2 nibbles  - left and right volume values, as described by the audio device reference
+* sample - 2 nibbles and 1 byte  - definition of the sample to be used. high nibble: index of sample to use. low nibble + byte: length of the sample to use
+
+available samples:
+
+* 0: saw
+* 1: main - program code
+* 2: piano
+* 3: triangular
+
+# second column of a channel
+
+* melody - 8 bytes  - midi notes corresponding to beats 0 to 7, from top to bottom.
+
+)
 
 %RTN { JMP2r }