refs #944 submitted herman's documentation, for revision