https://tom.preston-werner.com/2010/08/23/readme-driven-deve...

> As a byproduct of writing a Readme in order to know what you need to implement, you’ll have a very nice piece of documentation sitting in front of you. You’ll also find that it’s much easier to write this document at the beginning of the project when your excitement and motivation are at their highest. Retroactively writing a Readme is an absolute drag, and you’re sure to miss all kinds of important details when you do so.

Also a basic description of what your app is/does and what’s it’s trying to solve, a video demonstration also goes a long way. Make sure you use tags on the repo, it’s help with search discovery.

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