DEV Community

Discussion on: How to write a kickass README

Collapse
tautvydasderzinskas profile image
Tautvydas Derzinskas

Emojis is a matter of taste.

You are missing two important things:

  1. Table of contents. (allows you to see summary of your readme file without scrolling + quick navigation)
  2. Logo - makes your readme and whole project more professional
Collapse
scottydocs profile image
James.Scott Author

Agreed re:emojis and logo! Have made an edit. Thanks!

The risk of adding a TOC is you push all the important information like the intro/project summary etc further down. I’d only really use one if your README is incredibly long (or I’d move some of that content into another file).

Collapse
willvincent profile image
Will Vincent

I think if you've got enough info to warrant a TOC, that should follow the initial intro section of the document that describes what the thing is, etc.. AND, that's probably a good time to also think about splitting it into multiple files, ie: instead of a contributors section, a separate contributors.md file, etc.

Thread Thread
benracicot profile image
Ben Racicot

+1 this is what I did. Once it gets to a certain length ah... you kind of need one up top.