Add project level documentation

Write a better README.md and move the `succeeded ()` function to a more
logical place.