In BlogPost, Career

How To Write a Readme File For Your Coding Sample

If you’ve been in the Ruby programming language community for any length of time, one of the chief complaints you’ll hear is a lack of good documentation.

coding_sample_readme

Good documentation makes life easier for everyone

One of my managers always encouraged our team to write a good README file for any of our projects. This helped developers quickly get up to speed on how to run the application and any other nuanced details such as where to store a secret API key for talking to third party services.

Why a good readme for your coding sample?

A good readme file for your coding sample can showcase that you’re a good communicator using the written word. It’s not the be all and end all for landing your dream job, but it surely can help you stand out especially if other candidates are not doing as good a job.

Wouldn’t you rather have your coding sample be the one people can easily figure out how to use and run?

With that in mind, let’s go over a few ways to make sure you have a good readme for your coding sample.

Step 1 – Good grammar and spelling

With tools like Grammarly or the spelling and grammar check in your typical word processor, there’s no excuse these days for having typos and poor grammar in your readme.

First impressions count for a lot, especially during the initial interview phases.

Step 2 – Problem it solves and why

The next part of your readme file should explain at a high level what problem you are solving and why. It should be clear to anyone on the engineering team.

Here is an example from the very first Ruby on Rails gem I wrote:

Notice it’s a very high-level description of what the gem accomplishes and why it benefits the user.

Step 3 – Step by step installation instructions (and a live demonstration)

Clear and easy to follow installation instructions help anyone be able to see if your application is working. Hiring managers have very little time. They may not even bother installing your code project if it’s too hard.

That’s why it’s best to have something as close to a “1 click” installation process or a live demonstration. I usually have a live demonstration on the web (since I work in web application development) and step by step instructions.

Here is a small example of step by step instructions written in markdown I used for a previous coding project in Ruby:

Notice I even include they type of operating system I tested it on. This is just on the off-chance that they test it on OSx and it doesn’t work. This way they are at least aware of the platforms I actually tested it on.

Step 4 – Approaches and Tradeoffs

The last step is to talk about approaches and tradeoffs. This lets your reader know how you thought about the problem and what your solution offers. In fact, I might argue that this is just as important as an actual working solution.

This is because it lets the hiring manager know that you’re able to think about issues in a holistic way and that you’re a good problem solver. The real-world is all about tradeoffs.

Example of a good readme

This homework assignment is an example of what I think makes a good readme. Let’s go over why.

Diagram

You’ll notice there’s a class hierarchy diagram. I actually have never implemented this in any of my coding projects, but I think it would definitely make a nice touch if you have the time.

Analysis

Another awesome part of this readme is the Profiling section.

The author talks about the expected bottlenecks, assumptions, and how his program actually performed. This is the kind of analysis an engineering manager would love to see.

Summary

Your readme in your coding sample project is a good chance to show what kind of programmer you are. A properly formatted and well thought out readme can help you stand out from the crowd and land a good programming job.

Recent Posts