Comment by csours
4 days ago
The "Real" documentation is the implementation. Prioritize making the source code available and understandable.
Examples are very nice. One way to create examples is with test cases. Test cases can also be packaged with source code!
The user model an API exposes and the internal model to implement this can be very different. It's like trying to conclude from the transformation a clockwork does, what it's purpose is (keeping track of time passing). The user model never needs to occur explicitly in the code.