I think that the ordering is fine, moving the last paragraph up would intersperse it in the context discussion which isn't really better. I would suggest that people read the entire docstring before drawing conclusions or commenting ;).