You have just found a hard problem. :) More seriously I find depending on the users needs, different documentation are needed. Documentation for beginners. Specifications which include any gotcha that anyone ever tells you, also what it doesnt do that people try. And how-tos to get stuff done. And never believe anyone who tells you the code/test documents itself. It doesn't. It just means your trying to get the users to document it for you. Which isn't terrible if you have to do it to lower cost, but lowers uptake, and gives a worse experience.