A good README.md file can instantly tell viewers the project's purpose. It should include instructions on launching the project and the prerequisites needed for the build. But of course, added details can push a simple README file to become a useful reference document.
1. Markdown and Styling
Similar to websites and HTML, using markdowns properly makes for a more readable document. Following in that spirit, GitHub's README can render h1, h2, h3, h4, h5, and h6 headers displaying a hierarchy of information. Using header tags is possible by using a hashtag # for h1 and ###### for h6 with the in-between matching the pattern.
Similar to HTML markdown, README files can also make use of emphasis tags, lists, and adding links. Using these help bring attention to important terms by emphasizing them with bold, italics, strikethroughs. Though differing from HTML, this is done with asterisks *, underscores _ , and tildes ~.
If you add a link to a README file, it'll automatically transform into a hyperlink. Inline links are useful for turning text into a hyperlink. Lists can order information and help with readability. Line breaks are a little weird in my experience hit the 'enter/return' key once or twice and make a guess.
For more tips on how to style with markdown visit the Markdown Cheatsheet.
2. Coding Snippets
SOOOOOOOOOOO adding code previews and instructions in a place where you're sharing code and how it works seems pretty logical. Want to flex the code you've written or place instructions on where individuals should replace information makes this a brilliant tool. Environment keys, API keys, and such will need replacements when others using the project want it to work.
Markdown can include code blocks with back-ticks ``. GitHub supports syntax highlighting, making the code more readable. Using `I'm inline` makes the code inline. And using ```Wait I'm a code block``` makes it a block.
So you can do something along the lines of this:
3. Images
So I honestly wasn't aware that images could be added to a README file on GitHub. Though, if I could be even more honest, I wasn't giving much thought to my repos README files. They would include a summary of the project, my name, and methods of contact. But this 2020 year and it's many "wonderful", that's sarcasm, pitfalls provided me with time to update older projects and work on new ones. I'm curious if image support was a thing when I first started using GitHub.
Why use images? Humans are visual creatures. It's a great way to represent and display how the project looks and what it does. It also helps the README file stand out. Now I do think that if you don't need to use images, then don't! But hey, you can add in a logo for branding.
So, how can you do this? The URL of an image file needs to be enclosed in parenthesis. But for more guidance, visit the Markdown Cheatsheet.
4. Emojis
Use sparingly and when it makes the most logical sense. For a great list of supported emojis use the Emoji Cheat Sheet.
😃 :smile:
😉 :wink:
5. For The Badge
When I found For The Badge, I was impressed. The site has a sense of humor that matches anyone whose written a line of code in frustration, delivers a project despite push back from the dev team, or understands internet humor. There are also serious badges like what language the project could be made with, Creative Commons, and compatibility.
Badges I like on the list are:
Discover more on For The Badge.
Though I suggest this with some precaution, please do not go overboard and become badge happy. Having too many badges can make the README file go from looking intriguing and modern to overbearing and tacky.
There are different badges available through other services that are popular on GitHub.
Bonus: Videos and Making Use of Gifs
So this one is a bit tricky. Videos can't render in the README file. But let's say you have a screencast showcasing how the software functions or answer key usage questions, a video would be an ideal way to get the message across. The Markdown Cheatsheet provides a good workaround for having videos. The suggestion roughly explains having a picture that looks like a video player with a still image from the video, and when clicked, add a link, opens up the video on YouTube.
That's what sparked me to consider adding gifs of video clips in the README file. There is a contrast with how long the gif can be, but it's enough to display what I wanted.
Useful tools:
Recordit - for desktop screencast.
ttystudio - for terminal sessions.
MP4 to GIF converters - Online Converter, Zamzar, Convertio, and ezgif.
Summary
Generally, most people will glance at your README and pick up the vital information they need while skimming. They'll maybe star it and then leave. What this means is that your README file should be easy to read, instantly explain what your project is about, what it does, and how to make it work. Make it legible, use white space, and make sure it serves a purpose.
