diff --git a/README.md b/README.md
index e594bbb..79ffb47 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,11 @@
 # Rivet: static site genetator
-River takes a source directory containing a the file sources and produces an
-output directory that can actually be uploaded to a server.
+Rivet is a static site generator that takes a directory containing markdown
+markdown files (and a couple special ones) and generates an output directory
+that can be uploaded to a server.
+
+Rivet uses `lowdown(1)` to convert the markdown files to html, as such refer to
+the `lowdown(5)` manpage for the details of the dialect of markdown and the
+possible metadata that it can parse.
 
 ## Dependencies
 - [lowdown](https://kristaps.bsd.lv/lowdown/)
@@ -32,7 +37,16 @@ clean:
 	rm -rf ${DESTDIR}
 ```
 
-## Similar tools
+## The source directory
+The source directory tree should at least contain:
+
+- `index.md`: will be converted to `index.html`
+- `_header.html`: contains the stuff to be placed inside all headers
+- `_footer.html`: contains the stuff to be placed inside all footers
 
+Obviously anything can go in the source direcory, keep in mind that everything
+that is not markdown files will be just copied over.
+
+## Similar tools
 - [saait](https://git.codemadness.org/saait/file/README.html)
 - [ssg](https://www.romanzolotarev.com/ssg.html)
diff --git a/rivet.1 b/rivet.1
index 33caca4..886fad1 100644
--- a/rivet.1
+++ b/rivet.1
@@ -122,6 +122,29 @@ dst/
   - sitemap.xml
 .EE
 
+.SH BUGS
+The only bug I know of is that all links to markdown files will not be converted
+to links to html files during conversion:
+.PP
+test.md
+.EX
+# This is an example
+Here's the [link](cool-page.md)
+.EE
+.PP
+test.html
+.EX
+...
+<h1> This is an example </h1>
+<p> Here's the <a href="cool-page.md">link</a></p>
+.EE
+.PP
+As you can see the link to
+.I cool-page.md
+was not converted to
+.I cool-page.html
+as such the link is dead.
+
 .SH AUTHOR
 Alessandro Mauri <alemauri001@gmail.com>