Ask HN: Can you give tips on writing a README for project?
3 vseplet 5 5/24/2025, 2:48:07 PM
I'm currently finishing up the initial version of my experimental embeddable library designed for creating web applications without a build step.
But I'm not sure how to make the repository appealing and successful — something that makes people want to try it out, maybe even contribute or improve it.
https://github.com/vseplet/morph?tab=readme-ov-file#morph
So, I'd really appreciate any tips you have on writing a great README or structuring the repo — or pointing out any common mistakes I might have made along the way.
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
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.