add some pitfalls documentation