improving docs format and syntax