Oh yeah! We’re giving your README a makeover!
The README will be one of the first things someone sees when they view your project. Think of it as the subject line to your email, or the elevator pitch to your presentation. The README is the opportunity to get someone interested in your open source project, or to convince them that you’re an awesome developer or simply to show off the cool project you’ve been working on in your spare time.
Yet, sometimes the README is forgotten. I get it, the code just needs to work sometimes. But, I highly encourage you to take a look at your project’s READMEs and iterate on them.
Here are 3 areas to focus on when updating or creating your project READMEs.
Describe Your Project
I know, this probably sounds obvious, but you would be surprised. Dig deep enough into my Github profile and you’ll find a few repos with the default, outdated content, or—gasp—no READMEs at all. Writing about your work is a whole, big topic I’ll go into detail on another time. But, for your README, it can be straightforward.
Some questions to ask yourself when writing your project description include:
- What technologies does this project use?
- How can someone else use it?
- Why was it created? Or, what problem does it solve?
- Is this repo part of a bigger project or does it exist on its own?
Overall, a few lines explaining what your project is, what you used to build, and why, may be all you need to include. Think of the description as a concise, one-paragraph summary to your project to entice someone to know more.
Installation Instructions
Raise your hand if you’ve come across a README that had vague installation instructions!
To help save someone else from experiencing this, with my projects, I like to take a literal step by step approach to getting it up and running locally. I’ll start by doing a fresh clone of my repo on my Desktop or anywhere other than where I usually work on the project locally.
Then, write down exactly the next step is to getting it up and running. Include if there are any packages to include or API keys to fill in or if a certain command needs to be run in a specific directory. I like including the exact terminal commands in tick marks, for example git clone https://github.com/scrabill/cactus-buddy, for easy copy and pasting from the README.
Link To a Live Version
This may not apply to all projects, but it’s something to think about. If the goal of creating personal projects is to have something to show potential employers, you cannot always expect someone to be able to—or have the time to—clone it to their machine, get it up and running and then navigate the codebase.
In my bootcamp experience, a stretch task was to have the portfolio project built deployed online so that they can be used/viewed in the browser. Not only does this make a project easier to look at, experience, evaluate by others, but it also shows additional skills at being able to use cloud applications like Netlify, Heroku or Amazon Web Services.
Summary
If you can, I encourage you to take a critical eye at your own READMEs and do an audit. Put yourself in the shoes of someone who is coming across your project for the first time, with no context on what it’s about.
Some things to think about:
- Does your README accurately explain what your project is?
- What about how you built it?
- If the project is open to contributions, does the README clearly state that?
- Are the installation instructions missing any gaps or not work as expected?
Consider getting a friend, technical or non-technical, to take a look at your README and offer their initial thoughts. Other developers will likely be seeing your project, but so may potential hiring managers and recruiters. They may only have a few seconds to look at your project’s README to evaluate if you have the technical and communication skills they are looking for in an individual contributor.
What updates will you make to your README today?
Cover image by me!
The post Drab to Fab: Makeover Your Project README In 3 Steps appeared first on Shannon Crabill — Front End Software Engineer.
Top comments (2)
I take this and run with it in that I make a readme for every custom plugin or module I work on. It's a good exercise to add one even if someone else made the module, as the first step in refactoring.
That's a great idea! Even if you write something, you don't have to post it publically. But it may be beneficial later.