Fill in the blanks in files

README.md

@@ -1,27 +1,30 @@
 # nicoletta
 
-TODO: Write a description here
+[Nicoletta](https://github.com/ralsina/nicoletta) is a very (very) minimalistic static site generator I wrote using Python. This repo contains a reimplementation using the [Crystal language](https://crystal-lang.org/) I did in order to learn the language.
 
-## Installation
+I actually wrote down a [journal](journal.md) while doing it, too!
 
-TODO: Write installation instructions here
+## Build and Install
+
+You can build it by running `shards build` and install it by copying `bin/nicoletta` somewhere in yout PATH. Why would you do that, I have no idea.
 
 ## Usage
 
-TODO: Write usage instructions here
+Running `nicoletta` will:
 
+* Read a `conf` file, which should be YAML
+* Read markdown files from `posts/` which have YAML metadata on top
+* Use the template `templates/post.tmpl` to turn the markdown into a HTML fragment using the post's metadata
+* Use the template `templates/page.tmpl` to turn that fragment into a HTML page
+
+This repo contains examples for everything :-)
 ## Development
 
-TODO: Write development instructions here
+Let's not :-)
 
 ## Contributing
 
-1. Fork it (<https://github.com/your-github-user/crystal/fork>)
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request
-
+Why????
 ## Contributors
 
-- [Roberto Alsina](https://github.com/your-github-user) - creator and maintainer
+- [Roberto Alsina](https://ralsina.me) - creator and maintainer