updated docs slightly
more explicit docs should cover all the must-know basics