docs based on the disucssion with Bart, Jim, Steve