I personally feel that the problem with most documentation is that it always focuses on the how/what. That will always decay and be wrong. The code is the only

I personally feel that the problem with most documentation is that it always focuses on the how/what. That will always decay and be wrong. The code is the only truth in the end. The thing I suggest here is that if you are going to document the function, it should only be the WHY. The how can change and the documentation doesn't really decay. If you are making a new function you have to start with the why and if you can't then you shouldn't be adding a new interface. This also helps build a better picture of how the pieces interface together.