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
TLDRand be exhaustive later. Keep in mind your README will often be used instead of any documentation.
Top comments (0)