some documentation and shuffling