Updates for "general" page in documentation

Hi,

I am starting to use pygit2 for a little project. I've very grateful that it exists and would like to contribute a little bit. This isn't much but wanted to do a pull request to test the waters.

The first two commits are quite opinionated and really a matter of style. I am very happy if you ignore them.

The third commit is hopefully quite useful. It corrects an error in the constant name and provides additional information. I don't feel this is the most necessary documentation but I thought I'd give it a go. 

Cheers,
Michael