DEV Community

Cover image for 5 lesser known perks about READMEs

5 lesser known perks about READMEs

michaelb_91 profile image Michael B ・1 min read

Facts and advice you may not have come across yet:

  • A longer README may seem daunting but it will be indexed better by search engines. Include a generated table of contents for quick navigation.
  • Space out things; a 5-pages bloc is inscrutable, but 5 clearly separated sections are easily scrolled through. Don't let clarity be limited by the Markdown compact defaults, <!-- spacing :-) --> is your friend.
  • Logo / visual content ? Will make a difference for catching the attention of curious people just passing by, but often overlooked. Include serious & fun badges too! Those are (perceived as) warrant of quality and care from the maintainers.
  • Dark-mode friendliness - content that looks good in both clear and dark mode. Take extra care if your project is intended to be used by developers, or on your profile README.
  • Caring for both beginners and seasoned users; for example you can include a TLDR and be exhaustive later. Keep in mind your README will often be used instead of any documentation.

Discussion (0)

Editor guide