updating project documentation

the documentation is semi-dependent on Github Flavored Markdown,
particularly with respect to newlines and relative links.
it should look good online though.