update documentation for expected use case