Ask HN: Can you give tips on writing a README for project?

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.

4 points | by vseplet 14 hours ago

4 comments

  • nyoki 14 hours ago
    Tom Preston-Werner (GitHub, SemVer, Jekyll, etc.) has a great blog post about writing README files.

    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.

    [-]
    • vseplet 11 hours ago
      This idea shocked me with its simplicity, thank you
  • Jugurtha 7 hours ago
    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.

    - [1]: https://asciinema.org

  • speedylight 11 hours ago
    I’d suggest looking at other popular repos for inspiration. But at the very least you README should have information on how to run the program as an end user as well as a guide for developers on how to set up the dev environment such that they’re ready to go by following it.

    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.

  • FloatArtifact 6 hours ago
    If a project has a user interface, then there needs to be screenshots.