Hacker News Reader

Comment by rlnorthcutt | Hacker News Reader

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 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).

View on HN

Are you really shilling for the project without disclosing your affiliation?

https://github.com/rlnorthcutt

My apologies - it was a quick comment between calls :D In full disclosure, I'm the Head of DevRel at Appsmith. I didn't write this article, or contribute to it.

That being said, I do think its helpful, and I like the fact that other projects' READMEs are noted as good examples too.

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.

I totally agree - moderation is a good thing

It can also make your project inaccessible if you rely too heavily on images.

Personally I don't like too many images in a README. It's not a SHOWME. That's for your product page.

True - but not every project is a product. I run across open source projects all the time where the README is the product page. In those cases, I appreciate some images which can help me figure out if I want to try it out.

Otherwise, I have to install or set it up just to preview it, and I will personally not do that most of the time. So, I appreciate some images when they help me evaluate the project.

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

Same here, I like Draw.io but just did a sequence diagram showing a Stripe integration with actors, activations and notes in a few lines of Mermaid markdown 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

Reply on news.ycombinator.com