How to write a great README • Hacker News Board

Re: How to write a great README

#11

Post by bityard » Tue, Jul 18, 2023, 3:11 PM UTC

juujian wrote: post #6

drako999 wrote: post #2

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…

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

There was no procrastination, this is called "content marketing."

Re: How to write a great README

#12

Post by drako999 » Tue, Jul 18, 2023, 3:13 PM UTC

KnobbleMcKnees wrote: post #7

Please for the love of Cthulu remove that awful auto scroll from your homepage. It's practically unusable in a mobile webview. Great article though!

Thank you for the feedback! We'll fix it :)

Re: How to write a great README

#13

Post by distcs » Tue, Jul 18, 2023, 3:15 PM UTC

Since we are on this topic allow me to do an Ask HN comment here.

Ask HN: What are some good Readmes you have found?

Re: How to write a great README

#14

Post by spacebanana7 » Tue, Jul 18, 2023, 3:19 PM UTC

rlnorthcutt wrote: post #3

This 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…

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

Re: How to write a great README

#15

Post by [deleted] » Tue, Jul 18, 2023, 3:22 PM UTC

juujian wrote: post #6

drako999 wrote: post #2

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…

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

[deleted]

Re: How to write a great README

#16

Post by avgcorrection » Tue, Jul 18, 2023, 3:29 PM UTC

> https://github.com/appsmithorg/appsmith

That is more of a GitHub landing page than a readme.

> An effective README file needs to tell your audience what your project does, how to use it, and how they can help out.

The readme starts with an `a` image tag nested within a `p`.

Re: How to write a great README

#17

Post by coobird » Tue, Jul 18, 2023, 3:36 PM UTC

avgcorrection wrote: post #16

> https://github.com/appsmithorg/appsmith That is more of a GitHub landing page than a readme. > An effective README file needs to tell your audience what your project does, how to use it, and how they can help out. The readme starts with an `a` image tag nested within a `p`.

My thought as well.

If every project started to make their README filled with HTML (gah, why does Markdown allow arbitrary HTML...), I'd end up crying on the CLI as I frantically search for how to build the project in a sea of

, and
s...

Re: How to write a great README

#18

Post by avgcorrection » Tue, Jul 18, 2023, 3:41 PM UTC

coobird wrote: post #17

avgcorrection wrote: post #16

> https://github.com/appsmithorg/appsmith That is more of a GitHub landing page than a readme. > An effective README file needs to tell your audience what your project does, how to use it, and how they can help out. The readme starts with an `a` image tag nested within a `p`.

My thought as well. If every project started to make their README filled with HTML (gah, why does Markdown allow arbitrary HTML...), I'd end up crying on the CLI as I frantically search for how to build the project in a sea of , and s...

> gah, why does Markdown allow arbitrary HTML...

MarkDown is a misleading name.

Re: How to write a great README

#19

Post by KronisLV » Tue, Jul 18, 2023, 3:54 PM UTC

andai wrote: post #10

oslem wrote: post #4

Quick plug for makeareadme.com. I’ve always found it to be a good starting point for new projects.

https://www.makeareadme.com/ (clickable link!)

There's also this site which has a few different README templates: https://www.readme-templates.com/

Re: How to write a great README

#20

Post by atoav » Tue, Jul 18, 2023, 3:55 PM UTC

coobird wrote: post #17

avgcorrection wrote: post #16

> https://github.com/appsmithorg/appsmith That is more of a GitHub landing page than a readme. > An effective README file needs to tell your audience what your project does, how to use it, and how they can help out. The readme starts with an `a` image tag nested within a `p`.

My thought as well. If every project started to make their README filled with HTML (gah, why does Markdown allow arbitrary HTML...), I'd end up crying on the CLI as I frantically search for how to build the project in a sea of , and s...

Quite frankly I was happy with the arbitrary html part more often than it annoyed me. E.g. when I had to add a table that was just slightly out of markdowns comfort zone (merged cells).

Those who read my readmes were always happy with the content and never complaines about the html.