updates docs to cover common pitfalls