improve keyboard docs

Closes #957.