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.
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:
This is a ruby on rails gem that enables easy installation of the sharrre jQuery plugin.
It provides a simple way to add social media buttons to your rails application.
No more digging through APIs or copying and pasting code from developer docs just to install social media buttons for your rails application.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:
###Installation instructions / Run Instructions
I used the RVM package manager and you'll notice the .ruby-gemset and .ruby-version files in this code repository.
Step 1: *bundle install* to your RVM gemset (or whatever setup is most convenient for you)
Step 2: Run *ruby hp_calculator.rb* and start inputting your data
Step 2a: Press *q* or *CTRL+D* to stop the program
Step 3 (optional): Run *rspec spec* in the main directory to run the tests
###Requirements
This was created and tested on an Ubuntu 14.04 Linux system using Ruby 2.3.0. It should likely run on an OSx box without any trouble.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.
Class Hierarchy
|-------------------------| |------------|
| BinarySearchTree |--has-a----->| BSTNode |
|-------------------------| |------------|
^ ^ ^ ^
/ \ | |
is-a is-a | |
/ \ | |
/ |--------------| | |
/ | SplayTree |-has-a---| |
/ |--------------| |
/ is-a
/ |
|----------------| |------------|
| AVLTree |--has-a-------------------------->| AVLNode |
|----------------| |------------|
Analysis
Another awesome part of this readme is the Profiling section.
Our expected performance bottlenecks for the word-count program are... + the Splay operation for SplayTree + the insertHelp function for AVL, and + the PercolateDown operation for Heap
We chose these to be the bottlenecks because we assumed the function call
frequencies and costs. However, it turned out that some of these are not huge
bottlenecks at all. For example, Splay function doesn't take as much time as we
thought. Words that are inserted frequently don't take so much rotations
because they are already close to the root.
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.