Ways to up your game with a ReadMe.md on GitHub
What’s my biggest pet peeve of programming? Poor documentation.
If you’re going to write a ReadMe — you should be writing at least one for each repository that you create — then you might as well put a bit of muscle behind it…Mind muscle. Ba dum tss. All joking aside, it is important to think of your mind like a muscle. It needs its exercise or it can and will atrophy.
Please see below for an artist’s rendering of how this author feels on her “mental-workout day.”
Putting aside my razor-sharp wit, I’ve been wanting to put together some quick pointers for ReadMes. If you’re just starting to write this form of technical literature, you’ll probably face some critiquing. Lordy knows I have, and not all of it is fun. But that’s OK. It’s a part of learning. And so it is with great hope that I’ll now try and translate some of what I’ve learned into sage advice for my fellow newbies.
*I’m going to talk about these files as though they are simply about your repositories. If I incorporated every possibility for every sentence this post would be hefty. ex: “Why should you/your team/your business/others/other groups use ReadMes?” You get the point. I hope.*
Why do they matter?
ReadMes provide a rundown of the repository.
Why did you build this? What does it do? Did you encounter any bugs that another can learn from? Would you like help with your code? What did it look like when ran? And on, and on, and on.
You might be rolling your eyes and still wondering “sure but, why does it matter?” I mean, it’s your repository; you (hopefully) know how the code works. But there are still valid and valuable reasons why you should be writing one:
GitHub
GitHub creates the ability for anyone to see your work. Like I said before, its a rundown of your repository. Show others why they should take a moment and look at your work.
Sharing is caring
Did you just create an amazing animation library? What about that handy dandy algorithm that you absolutely love? Want to share them? Make them shine in your ReadMe! No, you don’t have to. But not doing so can easily lead to your target audience skipping over your repository altogether to find another option on Google.
Future employers will look at these
Sure, your code is immaculate. But can you explain that to a director whose time is limited? How well can you document your thoughts, code, progress, ups, downs, etc.? Work is about being part of a team. Use your ReadMe to demonstrate you’d be able to speak to other teammates.
Recruiters
Picture your average recruiter. Limited to no technical background, under a large demand and skimming hundreds of resumes. If you only show them code, you run the risk of being skimmed over for taking too much time to understand. Pull them in. Throw a few photos in there, tell them to check out the corresponding website (if applicable). Describe how you overcame an obstacle and how awesome you are for doing so. Tell them that you’re a hard-working programmer, because this might be the only thing they can understand on your GitHub.
You will forget your old projects
Oh my. How do I emphasize this enough? If the opinions of others mean nothing to you, then at the very least write a ReadMe for your future self. If not, you run the risk of being known as the “aggressive mumbler” at your local Starbucks. Which is, for the record, a totally unfair title. Sometimes you just have to ask yourself “WHY WOULD I ASSIGN THAT NAME TO AN API??” Or, “WHY DID I NAME IT ‘EXERCISE 20’ WHEN THERE’S NO 1–19???” Plus, it’s cool look back and reflect on how far you’ve come. :)
How to write one
Did you know ReadMes allow the ability to use markdown?? Who knew! Know who didn’t for an embarrassingly long time? This lady!! How, you ask? IT’S SO EASY!
ReadMes can be edited through either GitHub (as shown below) or through your preferred code editor. Markdown resembles HTML, but is actually it’s own entity. This repository goes through many aspects you can incorporate such as video tags, font manipulations, and more.
Other tips and tricks
Snapshots
Take snapshots of your work. Mac’s shortcut is shift-command-4. Your mouse becomes a + type tool and you can click and drag what aspects you want to showcase. Windows typically has a snipping tool installed. Same concept. Activate the snipping tool, click, and drag. Poof. People love photos. They’re easy to glance at and provide a good idea of your project.
What should you snap? Whatever you want to showcase or whatever helps others understand your project better. Snap what full screen vs mobile looks like. Snap your beautiful carousel mid-animate. Snap a test save in your database (please don’t snap sensitive information).
Code Snippets:
Don’t snap your code! Write it like a pro. This aspect can be found within the repository for markdown provided before, but I wanted to highlight this aspect. Simply use three backticks before the code, then close with three additional backticks
For even fancier results, after the first set of backticks, write out the code you’re writing in and your ReadMe will come out color-coded on GitHub. Look at those beautiful colors!
Make a screen recording
Demos are amazing. YouTube is easy. And QuickTime provides a wonderful tool for recording your screen.
Here’s a Mac tutorial on QuickTime. I haven’t personally screen recorded on a Windows; however, I’ve heard they have easy to use tools as well.
Do remember that videos are often large files. Do NOT add the screen recording video to a file within your project then push that file to GitHub. It probably won’t work. I tried. It didn’t work in my favor. Simply upload the video to YouTube and link the video tag.
//blanket example
<a href="http://www.youtube.com/watch?feature=player_embedded&v=YOUTUBE_VIDEO_ID_HERE
" target="_blank"><img src="http://img.youtube.com/vi/YOUTUBE_VIDEO_ID_HERE/0.jpg"
alt="IMAGE ALT TEXT HERE" width="240" height="180" border="10" /></a>//my ReadMe code with video and image
#Live Demo
<a href="http://www.youtube.com/watch?feature=player_embedded&v=-r-Tvb5xrN8" target="_blank"><img src="public/images/Home.png"
alt="journal analytics demo link to youtube" width="300" height="200"/></a>
Things to keep in mind
This doesn’t cover every aspect, and my ReadMes aren’t perfect. No one’s is. Be creative!
Each repository is unique.
Future employers are going to look at a ReadMe differently than you do, so remember your audience.
Don’t rely on the fact that your memory is better than Fry’s; we all forget.
I hope this provides you with a brief overview of ReadMes and their importance. If you have any suggestions that I didn’t mention, please comment!
Happy coding!
