Feature/revise spec

DO NOT MERGE. FOR DISCUSSION ONLY. @zdne @honzajavorek Please comment.

This PR updates the SPEC based on @zdne and my multiple discussions and refinements.

It also pulls in the current README with some typo fixes. 

@zdne I basically forked and update your branch for this PR into master. Would you prefer I just fork off of master and just create a branch the only adds the spec? Let me know.
You are first time using `<`and `>` here, everywhere else its just a description e.g. `- red (string) - A sample value`. While I understand where `<`and `>` comes from I would stick with the later, that is:

```
- name: Andrew (string) - A Description
```