diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..b25c15b
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1 @@
+*~
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..65aa969
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,25 @@
+INVENV = $(shell pip3 -V | grep 'venv')
+current_dir = $(shell pwd)
+
+prereqs: venvcheck FORCE
+	pip install -r requirements.txt
+
+venv: FORCE
+	python3 -m venv venv
+
+docs:
+	pdoc  --html ./src/harbourmaster.py --force
+
+venvcheck:
+ifeq ($(INVENV),)
+	$(error You should only run this from within the venv. Use '. ./venv/bin/activate')
+else
+	@echo "venv check passed\n"
+endif
+
+
+test: FORCE venvcheck
+	py.test -v  tests/ 
+
+
+FORCE:
diff --git a/README.md b/README.md
index 6fe74e3..191c891 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,32 @@
-# harbourmaster
+---
+title: Harbourmaster
+author: James Shuttleworth and YOUR NAME HERE
+---
+
+# HarbourMaster
+
 Harbourmaster is a simple port-scanning tool
+
+# Introduction
+
+This is a very simple tool, but it does (or will do) a few useful things.  
+
+In cybersecurity, we often have to work with data in different
+representations. For example, when creating payloads for exploits, we
+might have to switch between bytes represented as their ASCII values
+and their binary, decimal or hexadecimal (hex) representation.  For
+example, the capital letter A has the ASCII code 65.  65 in hex
+is 41. In octal it is 101, and in binary it is 01000001.
+
+
+# Completing Transcoder
+
+TODO:
+
+
+# TODO - things left to do before students get access
+
+ - Clear up TODO items
+ - Put proper pydoc generation in and fill in all docstrings
+ - Write bit about cloning repo
+
diff --git a/requirements.txt b/requirements.txt
new file mode 100644
index 0000000..0ea2890
--- /dev/null
+++ b/requirements.txt
@@ -0,0 +1,4 @@
+wheel
+colored
+pytest
+pdoc3
diff --git a/src/harbourmaster.py b/src/harbourmaster.py
new file mode 100644
index 0000000..6d1b93b
--- /dev/null
+++ b/src/harbourmaster.py
@@ -0,0 +1,16 @@
+#!python
+"""Simple program for scanning ports on a given host and acting on results"""
+import colored
+
+
+def testPort(host:str,portnum:int):
+    """Given a host (IP or name) and a port number, connect if possible and return any data transmitted.
+    
+    Args:
+      host (string): the host to scan. Can be an IP address or hostname
+      portnum (int): the port number, between 0 and 65535
+
+    Returns:
+      string or None: the data returned by the connection, or None if the connection failed.
+    """
+    return "Not implemented"
diff --git a/tests/test_hm.py b/tests/test_hm.py
new file mode 100644
index 0000000..e33b041
--- /dev/null
+++ b/tests/test_hm.py
@@ -0,0 +1,6 @@
+import pytest
+import sys
+sys.path.append("./src/")
+import harbourmaster
+
+#TODO: write tests