How to write a great README
appsmith.com
How to write a great README
1–10 of 56 posts
Re: How to write a great README
#2Hey 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!
Re: How to write a great README
#3This really stood out for me: 'We also think it is beneficial to show instead of tell wherever possible. We recommend using icons, images, and GIFs to keep it visually engaging and provide visual signposts — helping readers quickly navigate to the details that are important to them.'
We know that things like bulleted lists, headings, and paragraph structure can have a massive impact on readability... and I think those visual touches go even further.
Of course, just using icons doesn't do anything (And can make it worse), but if they are relevant, then it adds another layer of data. +1 on images and Gifs - I find it much easier to evaluate a project if I have some idea of what it looks like (Assumign it has a UI).
Re: How to write a great README
#4Quick plug for makeareadme.com. I’ve always found it to be a good starting point for new projects.
Re: How to write a great README
#5This really stood out for me: 'We also think it is beneficial to show instead of tell wherever possible. We recommend using icons, images, and GIFs to keep it visually engaging and provide visual signposts — helping readers quickly navigate to the details that are important to them.' We know that things like bulleted lists, headings, and paragraph structure can have a massive impact on readability... and I think thos…
To me, too much use of icons, images, and GIFs sort of looks spammy. But I think there's a middle-ground where you just use images to help explain the architecture and a GIF to show a demo but you don't go overboard with it all.
Re: How to write a great README
#6Hey 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…
Love the write-up, I only have one question. What actual work were you procrastinating on by writing it ;)
Re: How to write a great README
#7Please for the love of Cthulu remove that awful auto scroll from your homepage. It's practically unusable in a mobile webview.
Great article though!
Re: How to write a great README
#8Please for the love of Cthulu remove that awful auto scroll from your homepage. It's practically unusable in a mobile webview. Great article though!
+1 this is awful. I thought there was something wrong with my browser!
Re: How to write a great README
#9Hey 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…
Love the write-up, I only have one question. What actual work were you procrastinating on by writing it ;)
Most likely, replying to user queries :)
Re: How to write a great README
#10Quick plug for makeareadme.com. I’ve always found it to be a good starting point for new projects.
https://www.makeareadme.com/
(clickable link!)