issues/#391-scheduler-doco-assumptions

Related to #391, @johnsimons can you review?