refactor and expand docs on indexing rules, ala bill dueber