diff --git a/docs/cpu.md b/docs/cpu.md
index 6860bc8..3bc8717 100644
--- a/docs/cpu.md
+++ b/docs/cpu.md
@@ -55,6 +55,16 @@ by a source operand, or by source and target operands, depending on the opcode.
 | 15:14  | size   | operation size, e.g. 32 bits
 
 
+NOTE: Although in the instruction encoding the source operand comes first,
+followed by the target operand, the order is reversed in the fox32 assembly
+language. The following lines are equivalent:
+
+```
+cmp r1, r20
+data.16 0x8700 data.8 20 data.8 1
+```
+
+
 ### Operand types
 
 | value | description           | size of operand  | what's actually stored?
diff --git a/docs/instructions.md b/docs/instructions.md
index 15ed1ca..5cbd730 100644
--- a/docs/instructions.md
+++ b/docs/instructions.md
@@ -1,53 +1,68 @@
 # Fox32 instructions
 
 This file describes every fox32 instruction in detail. For a general
-description of the fox32 CPU, see cpu.md.
+description of the fox32 CPU and instruction encoding details, see [cpu.md](./cpu.md).
 
-## NOP: no operation
-## ADD: add
-## MUL: multiply (unsigned)
-## AND: bitwise AND
-## SLA: shift left
-## SRA: shift right arithmetic (with sign extension)
-## BSE: bit set
-## CMP: compare
-## JMP: absolute jump
-## RJMP: relative jump
-## PUSH: push value to stack
-## IN: get input from I/O bus
-## ISE: set interrupt enable flag
-## MSE: set MMU enable flag
-## HALT: halt CPU
-## INC: increment (add 1)
-## OR: bitwise OR
-## IMUL: multiply (signed)
-## SRL: shift right logical (with zero extension)
-## BCL: bit clear
-## MOV: move value
-## CALL: absolute call
-## RCALL: relative call
-## POP: pop value from stack
-## OUT: output on I/O bus
-## ICL: clear interrupt enable flag
-## MCL: clear MMU enable flag
-## BRK: debug breakpoint
-## SUB: subtract
-## DIV: divide (unsigned)
-## XOR: bitwise XOR
-## ROL: rotate left
-## ROR: rotate right
-## BTS: test if bit set
-## MOVZ: move value and clear upper bits in target register
-## LOOP: absolute loop
-## RLOOP: relative loop
-## RET: return from function
-## INT: raise interrupt
-## TLB: flush TLB and set page directory pointer
-## DEC: decrement (subtract 1)
-## REM: calculate remainder of division (unsigned)
-## NOT: bitwise NOT
-## IDIV: divide (signed)
-## IREM: remainder (signed)
-## RTA: calculate address relative to instruction pointer
-## RETI: return from interrupt
-## FLP: flush page from TLB
+
+## Arithmetic instructions
+
+### ADD: add
+### SUB: subtract
+### INC: increment (add 1)
+### DEC: decrement (subtract 1)
+### CMP: compare
+### AND: bitwise AND
+### OR: bitwise OR
+### NOT: bitwise NOT
+### XOR: bitwise XOR
+### BSE: bit set
+### BCL: bit clear
+### BTS: test if bit set
+### SLA: shift left
+### SRA: shift right arithmetic (with sign extension)
+### SRL: shift right logical (with zero extension)
+### ROL: rotate left
+### ROR: rotate right
+### MUL: multiply (unsigned)
+### IMUL: multiply (signed)
+### DIV: divide (unsigned)
+### IDIV: divide (signed)
+### REM: calculate remainder of division (unsigned)
+### IREM: remainder (signed)
+### NOP: no operation
+### MOV: move value
+### MOVZ: move value and clear upper bits in target register
+### RTA: calculate address relative to instruction pointer
+
+## Stack instructions
+
+### PUSH: push value to stack
+### POP: pop value from stack
+
+## Control flow instructions
+
+### JMP: absolute jump
+### RJMP: relative jump
+### LOOP: absolute loop
+### RLOOP: relative loop
+### CALL: absolute call
+### RCALL: relative call
+### RET: return from function
+### RETI: return from interrupt
+### ISE: set interrupt enable flag
+### ICL: clear interrupt enable flag
+### BRK: debug breakpoint
+### INT: raise interrupt
+### HALT: halt CPU
+
+## MMU instructions
+
+### MSE: set MMU enable flag
+### MCL: clear MMU enable flag
+### FLP: flush page from TLB
+### TLB: flush TLB and set page directory pointer
+
+## I/O instructions
+
+### IN: get input from I/O bus
+### OUT: output on I/O bus