Our great sponsors
-
appsmith
Platform to build admin panels, internal tools, and dashboards. Integrates with 25+ databases and any API.
-
mermaid
Generation of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown
-
SurveyJS
Open-Source JSON Form Builder to Create Dynamic Forms Right in Your App. With SurveyJS form UI libraries, you can build and style forms in a fully-integrated drag & drop form builder, render them in your JS app, and store form submission data in any backend, inc. PHP, ASP.NET Core, and Node.js.
-
player
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)
-
payload
The best way to build a modern backend + admin UI. No black magic, all TypeScript, and fully open-source, Payload is both an app framework and a headless CMS.
-
nanostores
A tiny (286 bytes) state manager for React/RN/Preact/Vue/Svelte with many atomic tree-shakable stores
-
-
InfluxDB
Power Real-Time Data Analytics at Scale. Get real-time insights from all types of time series data with InfluxDB. Ingest, query, and analyze billions of data points in real-time with unbounded cardinality.
-
-
-
-
-
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.
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
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
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
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
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?
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?
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
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.
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.
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.
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.
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.