improve documentation, though there's still much to be done