From eb39902e286703902dc3947174b5ce8131b795c5 Mon Sep 17 00:00:00 2001
From: Jonathan Lamothe <jonathan@jlamothe.net>
Date: Tue, 13 Aug 2024 20:32:55 -0400
Subject: [PATCH] added basic information to `README.md`

---
 README.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 55 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 46b08b5..ef3ade4 100644
--- a/README.md
+++ b/README.md
@@ -16,7 +16,59 @@ You should have received a copy of the GNU Affero General Public
 License along with this program.  If not, see
 <https://www.gnu.org/licenses/>.
 
-## Important Note
+## Executive Summary
 
-This software is experimental and should be considered a subject to
-change at any time.
+This is an educational tool designed for experimentation with Hamming
+codes.  A hamming code consists of a certain number of data bits and a
+smaller number of check bits.  The data bits are used to store
+information, and the check bits are used to verify the integrity of
+the message as a whole.  In the event of a single bit error, the code
+provides enough information to restore the original message.
+
+For more information on hamming codes, see [this
+video](https://youtu.be/X8jsijhllIA) on YouTube.
+
+## Installation
+
+This program is written in [Haskell](https://haskell.org) using the
+Stack package manager.  The easiest way to install it is by first
+installing [GHCup](https://www.haskell.org/ghcup/), and then from
+within the project directory, run the command: `stack install`
+
+You should then be able to run it by simply typing `hamming` on the
+command line.  There are currently no command-line options.
+
+## Usage
+
+When run, the program will display a 16-bit extended hamming code in a
+4x4 grid.  The rows and columns are numbered 0-3 and a green check
+mark or red X will be displayed in the upper left hand corner of the
+code indicating whether or not it's valid.  The check bits will be
+highlighted to make them more easily identifiable.
+
+The program begins in display mode, but can be switched into edit mode
+to change the value of the individual bits.  While in edit mode, the
+cursor will appear indicating the bit currently being edited.
+
+## Keyboard Commands
+
+In both modes of operation, these keys will have the following
+effects:
+
+- CTRL-C/Q: Quit the program.
+- C: Set the check bits to reflect the values in the data bits.
+- V: Correct to the nearest valid code (if possible).
+- R: Reset the code to all zeroes.
+
+### Display Mode
+
+- E: Enter edit mode.
+
+### Edit Mode
+
+- ESC: Return to display mode.
+- Up/K: Move the cursor up.
+- Down/J: Move the cursor down.
+- Left/H: Move the cursor left.
+- Right/L: Move the cursor right.
+- F: Flip the bit under the cursor (1 becomes 0; 0 becomes 1).