Hi, there! 👋

I created ember-container-query and am happy with how its README turned out. I like it for these reasons:

• Continuous integration badges to deliver confidence
• Quick demo GIF
• 1-line installation
• List of practical applications
• <summary> tags to hide details and not overwhelm first-time visitors

ember install ember-container-query

/var/folders/2z/93zyyhx13rs879qr8rzyxrb40000gn/T/broccoli-689520dxo26a682Mz/out-529-broccoli_merge_trees/assets/vendor.js:121232
  return this.args.features ?? {};
                             ^
SyntaxError: Unexpected token '?'

'use strict';
const browsers = [ ... ];
module.exports = {
  browsers,
  node: 'current'
};

I spend a lot of time in Postwoman's readme.

hoppscotch / hoppscotch

👽 A free, fast and beautiful API request builder used by 75k+ developers. https://hoppscotch.io

A free, fast and beautiful API request builder

Helps you create requests faster, saving precious time on development - Subscribe

_{Built with ❤︎ by
liyasthomas and
contributors}

---

Chat: Telegram, Discord

Donate: GitHub Sponsors, Open Collective, Patreon, PayPal

Table of contents

---

• Features
• Demo
• Usage
• Built with
• Developing
  • Browser based development environment
  • Local development environment
  • Docker compose
• Docker
• Releasing
• Contributing
• Continuous Integration
• Versioning
• Change log
• Authors
  • Lead Developers
  • Testing and Debugging
  • Collaborators
  • Thanks
  • Financial Contributors
    • Organizations
    • Individuals
  • Code Contributors
• License
• Acknowledgements
• Badges

---

Features ✨

❤️ Lightweight: Crafted with minimalistic UI design.

⚡️ Fast: Send requests and get/copy responses in real-time.

Methods:

• GET - Retrieve information about the REST API resource
• HEAD - Retrieve response headers identical to those of a GET request, but without the response body.
• POST - Create a REST API resource
• PUT - Update a REST API resource
• DELETE - Delete a REST…

View on GitHub

Not in context with readme but if you check how Kent Dodds writes his issues and also guidelines for newbies, it's definitely inspiring in context of knowledge-transfer. I follow him to see how he transfers his learning to newbies and others. His github and twitter activity on that part is amazing.

I like the emoji in your titles, makes the README entertaining, well done 👍

I can't off the top of my head think of a specific project with a great README, but a platform I associate with great READMEs is npmjs.com. The convention there seems to be "lead by example." It seems to me anyway that usually the first item in the doc for a node module is an example instantiation of call of whatever it is. Contrast this with UNIX man pages, where it's almost my reflex to press G (go to bottom of man page) which is where there's usually one or more usage examples, above which is an exhaustive list of all possible command switches or function parameters. (cw pun ahead) You might say the npmjs.com philosophy is "lead by example" while the UNIX man pages philosophy is "bury the lede."

I made one recently. It's for my icon open-source project called Neu Icons. At the beginning of writing the README, I found many issues about how I can make it visually as I want. But time goes by I learned how the markdown works and so on. And now I am pretty happy with it.

The importance of writing README for me have these aspects:

• Describe what the project is for
• Clear information about how to use it
• Write as detail as possible, it will help people to understand the project, a lot
• Give some notes if some features are under construction
• Give some credits to people who helped to bring the project live to the community

Having a monorepo like ours, didn't actually made it easy to compose a single entry README. You can't for example display an "installation guide" if the repo contains many installation guides.

After some thoughts, I went for an introduction and a list of all its apps, components, functions etc. It also displays a link to the developer documentation.

Any ideas of improvements?

My programming language, Blue, doesn't use the README, but it does have a pretty detailed documentation page: kiraprograms.com/blue/help.html. It describes the project on the main page: kiraprograms.com/blue/help.html, and it doesn't have instructions for installation because it's 100% in the browser. I spent over half of the time just working on the documentation, which, in theory, could also be used as a tutorial. It's probably not much compared to massive projects made by teams of programmers, but it took a while consitering that I did it totally on my own.

I have spent a lot of time on this one. I hope you can give feedbacks on this. (I find my README great btw c:)

Thanks for sharing!

How did you come up with your README format? And regarding contributions—do you get them frequently? Do they need to be formatted or structured in a particular way? What about issues?