4 ms·

Hey everyone, I'm a co-founder and CPO at Appsmith. I have used this article to share our experiences with writing a great README, and I think it would be benef

Hey everyone, I'm a co-founder and CPO at Appsmith. I have used this article to share our experiences with writing a great README, and I think it would be beneficial to hear about everyone's experiences with what actually makes a README useful for an open source project. Would love your feedback on the topic. And of course, if you have any feedback on how we can make Appsmith's README more useful for you, please let us know!

juujian 3y ago
Love the write-up, I only have one question. What actual work were you procrastinating on by writing it ;)
- drako999 3y ago
  Most likely, replying to user queries :)
- bityard 3y ago
  There was no procrastination, this is called "content marketing."
- deleted 3y ago
  [deleted]
dcow 3y ago
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. Next, contributors sections are dumb. Github is a better tool to use to view contributors (https://github.com/appsmithorg/appsmith/graphs/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. Finally, you have a "getting started in 100 seconds" image CTA in your features section. Doesn't make any sense to me and again there's no supporting text. 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. Edit: here's a readme to compare/contrast with https://github.com/Lxtharia/minegrub-theme https://github.com/Lxtharia/minegrub-theme
- ShadowBanThis01 3y ago
  Also: Don't use Markdown. Yes, it's "human-readable," but it's full of code text and there are almost no stand-alone VIEWERS for it. The rampant use of Markdown while there's a lack of viewers for it is baffling. And no, I don't count editors in which you can invoke a "preview" of the Markdown. Why publish in a format that must be loaded into an editor and then "previewed?" You might as well just use plain text, since the reader is just going to be seeing the raw text of the file anyway. Or have stand-alone viewers (not editors) for Markdown proliferated since I last checked a couple years ago?
  - dcow 3y ago
    I think markdown reads very nicely in text form. Title === Summary of the page # H1 Intersting Topic The most important part of [1] is... ## H2 What others say > Quote from somebody. Callout something. And then it's implemented like: ``` // this code is a demonstration of how to query foo func foo() { does_thing(); } ``` # Conclusion You should use markdown to structure your documents. [1]: https://example.com
    - ShadowBanThis01 3y ago
      I said yes, you can read it. But I also noted that it's riddled with ## and other junk that doesn't do anything beneficial because you're seeing plain text. So why have detracting, non-informational characters in there?
      - dcow 3y ago
        My point is the ## provide structure and for me help to visually lay out the document, so I like reading markdown. To each their own.
      - OrderlyTiamat 3y ago
        > riddled with ## and other junk I'd argue in favor of those. A competent text editor (let's say no older than 40 years old) can highlight and/or render that. When using base markdown, those things add structure to the document. I'd much rather see a markdown file with basics like headers and code sections (which are usually highlighted correctly) than a raw .txt file. however I think your argument goes doubly hard when dealing with these more advanced html integrated readmes. The md file of the example readme is not well readable when opened in a text file to me- and there's actually very little content there! I prefer a more minimal approach where opening the .md file gives me the information I need, and opening it in a rendered environment gets me some niceties (perhaps you've got badges with coverage or versions nrs idk). But it should work in both.
yonasb 3y ago
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 https://github.com/undb-xyz/undb#-tech-stack and here https://github.com/steven-tey/novel#tech-stack 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?
timetraveller26 3y ago
*A self proclaimed great README
- sedatk 3y ago
  I was gonna say... what's the benchmark they used to decide it was great? Did they win the best README award somewhere?

juujian 3y ago

Love the write-up, I only have one question. What actual work were you procrastinating on by writing it ;)

drako999 3y ago
Most likely, replying to user queries :)
bityard 3y ago
There was no procrastination, this is called "content marketing."
deleted 3y ago
[deleted]

dcow 3y ago

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. Next, contributors sections are dumb. Github is a better tool to use to view contributors (https://github.com/appsmithorg/appsmith/graphs/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. Finally, you have a "getting started in 100 seconds" image CTA in your features section. Doesn't make any sense to me and again there's no supporting text. 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. Edit: here's a readme to compare/contrast with https://github.com/Lxtharia/minegrub-theme https://github.com/Lxtharia/minegrub-theme

ShadowBanThis01 3y ago
Also: Don't use Markdown. Yes, it's "human-readable," but it's full of code text and there are almost no stand-alone VIEWERS for it. The rampant use of Markdown while there's a lack of viewers for it is baffling. And no, I don't count editors in which you can invoke a "preview" of the Markdown. Why publish in a format that must be loaded into an editor and then "previewed?" You might as well just use plain text, since the reader is just going to be seeing the raw text of the file anyway. Or have stand-alone viewers (not editors) for Markdown proliferated since I last checked a couple years ago?
- dcow 3y ago
  I think markdown reads very nicely in text form. Title === Summary of the page # H1 Intersting Topic The most important part of [1] is... ## H2 What others say > Quote from somebody. Callout something. And then it's implemented like: ``` // this code is a demonstration of how to query foo func foo() { does_thing(); } ``` # Conclusion You should use markdown to structure your documents. [1]: https://example.com
  - ShadowBanThis01 3y ago
    I said yes, you can read it. But I also noted that it's riddled with ## and other junk that doesn't do anything beneficial because you're seeing plain text. So why have detracting, non-informational characters in there?
    - dcow 3y ago
      My point is the ## provide structure and for me help to visually lay out the document, so I like reading markdown. To each their own.
    - OrderlyTiamat 3y ago
      > riddled with ## and other junk I'd argue in favor of those. A competent text editor (let's say no older than 40 years old) can highlight and/or render that. When using base markdown, those things add structure to the document. I'd much rather see a markdown file with basics like headers and code sections (which are usually highlighted correctly) than a raw .txt file. however I think your argument goes doubly hard when dealing with these more advanced html integrated readmes. The md file of the example readme is not well readable when opened in a text file to me- and there's actually very little content there! I prefer a more minimal approach where opening the .md file gives me the information I need, and opening it in a rendered environment gets me some niceties (perhaps you've got badges with coverage or versions nrs idk). But it should work in both.

yonasb 3y ago

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 https://github.com/undb-xyz/undb#-tech-stack and here https://github.com/steven-tey/novel#tech-stack 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?

timetraveller26 3y ago

*A self proclaimed great README

sedatk 3y ago
I was gonna say... what's the benchmark they used to decide it was great? Did they win the best README award somewhere?