improved documentation, addressing #30