How to Write a Great Readme

1. appsmith

   1 262 39,980 9.6 TypeScript

   Platform to build admin panels, internal tools, and dashboards. Integrates with 25+ databases and any API.

   

   One spot where your readme misses the mark: it can't be read outside of github (or some rendering engine). Markdown is supposed to be human readable. Instead you say "here's how app smith works" and then plop a big image. That doesn't help anybody understand what your project does by reading the readme. Images and diagrams are super helpful, but they should accompany thoughtful prose. This is also important as an accessibility consideration.

   The contributors sections are dumb. Github is a better tool to use to view contributors (https://github.com/appsmithorg/appsmith/graphs/contributors). Other projects before github would have an authors and/or contributors file. I don't care about the contributors when I'm trying to understand how your project works, it's just shameless marketing in that position.

   You have a "getting started in 100 seconds" image CTA in your features section. Doesn't make any sense to me.

   Overall I'd suggest focusing on improving your readme to be more useful and less of a marketing tool (it can still market its value lightly) and instead explain how the software works and how to get up and running with it.

   Overall I'd score your readme 4/10.

2. SaaSHub

   www.saashub.com featured

   SaaSHub - Software Alternatives and Reviews. SaaSHub helps you find the best software and product alternatives

   

3. mermaid

   2 176 88,430 9.9 TypeScript

   Generation of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown

   

   I like using mermaid diagrams [1] in readme files and docs.

   They're easier to read than plain text explanations for architectural layouts/customer journeys but easier to modify than images and GIFs.

   Also natively supported in many flavours of markdown like Gitlab.

   [1] https://github.com/mermaid-js/mermaid

4. player

   3 2 3,535 8.0 TypeScript

   UI components and hooks for building video/audio players on the web. Robust, customizable, and accessible. Modern alternative to JW Player and Video.js. (by vidstack)

   

   vidstack is very light on technical details but starts with a concise intro and a screenshot, as well as relevant links: https://github.com/vidstack/player

   payload is well-structured in general: https://github.com/payloadcms/payload

   nanostores starts out with an intro and telling code examples, followed by lots of technical details: https://github.com/nanostores/nanostores

5. payload

   4 183 42,940 9.9 TypeScript

   Payload is the open-source, fullstack Next.js framework, giving you instant backend superpowers. Get a full TypeScript backend and admin panel instantly. Use Payload as a headless CMS or for building powerful applications.

   

   vidstack is very light on technical details but starts with a concise intro and a screenshot, as well as relevant links: https://github.com/vidstack/player

   payload is well-structured in general: https://github.com/payloadcms/payload

   nanostores starts out with an intro and telling code examples, followed by lots of technical details: https://github.com/nanostores/nanostores

6. nanostores

   5 22 7,413 7.8 TypeScript

   A tiny (286 bytes) state manager for React/RN/Preact/Vue/Svelte with many atomic tree-shakable stores

   

   vidstack is very light on technical details but starts with a concise intro and a screenshot, as well as relevant links: https://github.com/vidstack/player

   payload is well-structured in general: https://github.com/payloadcms/payload

   nanostores starts out with an intro and telling code examples, followed by lots of technical details: https://github.com/nanostores/nanostores

7. undb

   6 17 2,943 9.9 TypeScript

   🚀 Private first self-hosted no code database & BaaS.

   

   Great guide. One thing that seems to be missing is something I see in a lot of README's: a list of the core tech stack being used in the repo. Good examples here https://github.com/undb-xyz/undb#-tech-stack and here https://github.com/steven-tey/novel#tech-stack. Did you already consider adding this as part of the guide and decide against it, or was it just not something you thought to add?

8. novel

   7 23 16,200 8.4 TypeScript

   Notion-style WYSIWYG editor with AI-powered autocompletion.

   

   Great guide. One thing that seems to be missing is something I see in a lot of README's: a list of the core tech stack being used in the repo. Good examples here https://github.com/undb-xyz/undb#-tech-stack and here https://github.com/steven-tey/novel#tech-stack. Did you already consider adding this as part of the guide and decide against it, or was it just not something you thought to add?

9. revenut-web

   8 3 4 10.0

   Discontinued SaaS metrics in a nutshell

   Same here, I was using Draw.io but just did a sequence diagram showing a Stripe integration in Mermaid.js on a GitHub readme:

   https://github.com/hbcondo/revenut-web#-workflow

   But that diagram just renders as code for the same readme via GitHub Pages:

   https://revenut.com

10. LGV_TZ_Lookup

    9 4 47 3.8 PHP

    Server for Matching Long/Lat to Timezone

    

    I generally have a “What Problem Does This Solve?” section in my READMEs.

    https://github.com/LittleGreenViper/LGV_TZ_Lookup#what-probl...

    https://github.com/LittleGreenViper/LGV_MeetingServer#what-p...

    https://github.com/RiftValleySoftware/RVS_Spinner#what-probl...

    https://github.com/RiftValleySoftware/RVS_BlueThoth#what-pro...

    https://github.com/RiftValleySoftware/RVS_PersistentPrefs#wh...

    etc.

11. LGV_MeetingServer

    10 2 1 5.1 PHP

    An aggregation server for meeting list servers.

    

    I generally have a “What Problem Does This Solve?” section in my READMEs.

    https://github.com/LittleGreenViper/LGV_TZ_Lookup#what-probl...

    https://github.com/LittleGreenViper/LGV_MeetingServer#what-p...

    https://github.com/RiftValleySoftware/RVS_Spinner#what-probl...

    https://github.com/RiftValleySoftware/RVS_BlueThoth#what-pro...

    https://github.com/RiftValleySoftware/RVS_PersistentPrefs#wh...

    etc.

12. RVS_Spinner

    11 9 25 3.7 Swift

    A Fancy "Popup Prize-Wheel Spinner" UIControl

    

    I generally have a “What Problem Does This Solve?” section in my READMEs.

    https://github.com/LittleGreenViper/LGV_TZ_Lookup#what-probl...

    https://github.com/LittleGreenViper/LGV_MeetingServer#what-p...

    https://github.com/RiftValleySoftware/RVS_Spinner#what-probl...

    https://github.com/RiftValleySoftware/RVS_BlueThoth#what-pro...

    https://github.com/RiftValleySoftware/RVS_PersistentPrefs#wh...

    etc.

13. RVS_BlueThoth

    12 2 15 3.7 Swift

    A Native Swift Core Bluetooth LE Central (Client) Abstraction Driver

    

    I generally have a “What Problem Does This Solve?” section in my READMEs.

    https://github.com/LittleGreenViper/LGV_TZ_Lookup#what-probl...

    https://github.com/LittleGreenViper/LGV_MeetingServer#what-p...

    https://github.com/RiftValleySoftware/RVS_Spinner#what-probl...

    https://github.com/RiftValleySoftware/RVS_BlueThoth#what-pro...

    https://github.com/RiftValleySoftware/RVS_PersistentPrefs#wh...

    etc.

14. RVS_PersistentPrefs

    13 1 2 3.6 Swift

    A Simple Class For Basic Persistent Storage

    

    I generally have a “What Problem Does This Solve?” section in my READMEs.

    https://github.com/LittleGreenViper/LGV_TZ_Lookup#what-probl...

    https://github.com/LittleGreenViper/LGV_MeetingServer#what-p...

    https://github.com/RiftValleySoftware/RVS_Spinner#what-probl...

    https://github.com/RiftValleySoftware/RVS_BlueThoth#what-pro...

    https://github.com/RiftValleySoftware/RVS_PersistentPrefs#wh...

    etc.

Suggest a related project