improved spec docs