more explicit docs + a few corrections & questions