#7 Documentation update

[A. MacKenzie]

Update documentation in general, and make sure that where there are choices it clearly identifies the choices. Where there are choices with a preferred option it should be identified. Where there are not choices it must say "must". With all choices try to include what the consequences will be of the choice.