Never forget:

The worst person to write documentation is the implementer, and the worst time to write documentation is after implementation. Doing so greatly increases the chance that interface, implementation, and documentation will all have problems.

Michi Henning: API Design Matters in ACM Queue