rename some of the patterns for clarity and add documents