refactor: improves documentation structure, also tides up global variable references