I usually write the README and documentation before writing the code. I then shop it around and ask people if it makes sense.
The initial version of the code is stubs that, if you follow the code examples given in the documentation, return hard-coded values.
I went to the extreme of giving the docs to non-developers who've never written a single line of code in their entire life, giving them an interpreter, and asking them to follow the docs without providing any help. If they could do it, developers wouldn't have a problem.
One must resist the temptation to help and should only observe how the users "misuse" the code. When they make a mistake, it's usually a good indicator of bad design, which is promptly corrected.
There's also a good tool called asciinema[1] that helps you record terminal sessions.
The initial version of the code is stubs that, if you follow the code examples given in the documentation, return hard-coded values.
I went to the extreme of giving the docs to non-developers who've never written a single line of code in their entire life, giving them an interpreter, and asking them to follow the docs without providing any help. If they could do it, developers wouldn't have a problem.
One must resist the temptation to help and should only observe how the users "misuse" the code. When they make a mistake, it's usually a good indicator of bad design, which is promptly corrected.
There's also a good tool called asciinema[1] that helps you record terminal sessions.
- [1]: https://asciinema.org