better docs and spec