update docs for issue #26 and #27