You work hard to put together projects that you share with the world live and on Github/Codepen/Codesandbox in hope one day to show potential employers who have at best a few minutes of attention to dedicate them how far you've come and how much you've learned. Neglecting to document your work correctly is a missed opportunity to start that conversation right away and effectively bring them up to speed about what the project is about and what you got out of it.
A well-documented README can go a long way to not only give readers a concise but detailed peek at your project but also help you remember months later --during an interview maybe-- what were your thoughts when you were fully immersed in it. This documentation will also be a confidence booster throughout your journey by allowing you to look back and see how far you've come.
Following is a short list of information that goes beyond the common basic descriptions of what your app does and how to fork it.
Here is what you should consider including to your README for maximum impact:
1) Timestamp
A timestamp on each project will build a visual of your journey as a developer, just like on a resume. Don't rely of Github's "updated 4 months ago" timeline to give your audience an idea of how long ago you've published your project; the date of the last commit will be affected by any minor change you add to clean it up. Instead, go for:
Published on: DATE
Deployed on: DATE
2) Why did you undertake the project?
Briefly state what got you motivated to spend all those hours on this project. Was it an assignment? A bet? A challenge to tweak a feature from another project? A passion for a topic? A need to help someone? A collaboration? A way to learn a framework? etc.
3) Scope / User story
Explain in 1-2 sentence what your project does. What can the users expect?
4) List of features
Building on the previous section, expand on the list of functionalities and characteristics of your project. Keep it a concise list. Is your site responsive? Does it save data? Is it SEO-optimized?
5) Technologies / Stack used
List the technologies you used or had to learn to bring this project to fruition. Does it connect to an API? What framework did you use? Database? Web hosting?
6) Lessons learned
Here is the opportunity to explain how this project helped you progress. What did you learn along the way? What was hard? Unexpected? What did you have to research specifically? Did you have to reach out with questions?
7) Wish list
Given more time, what would you add or fine-tune? Are you going to revisit it at a later date to add some features? What would be nice to have? What will be in version 2.0? Consider adding a roadmap if you're still working on a live project.
8) Credits
Did you use a tutorial? A starter pack or a template? Did you fork an existing project? Did you collaborate with someone? Don't forget to include it in your README.
To sum it up:
Keeping this detailed list short and sweet will let a potential employers gain an easy insight into your learning journey. Again, as their time is limited, being concise is paramount. Bonus: On top of mastering markdown formatting you'll also demonstrate your ability to go beyond coding and document your work, a desirable skill that can set you apart from other candidates.
Do you add anything else to your project documentation? Share it in a comment below!
Top comments (8)
Thank you for sharing this list!
In our case one information which was often requested to be added was a CONTRIBUTING guide to our project. If that's maybe too much information to be displayed in the README, it's probably good to link or reference it too.
Badges from Shields.io is a good way to summarize info too. I recently landed on the Postwoman project's README and I think it's a nice usage of badges. Notably the way they display the last release date, which would match your good idea of displaying TIMESTAMP.
This Postwoman's README is slick! Great example.
Thank you 😄
Thank you for this post!
Usually, I used README only as an instruction 'How to run ...'. I saw others
README, but didn't much pay attention to the ways of how they formate it.s README file, to make it more readable and full.So I will try tips, which you provided, in my next project
I wrote almost the same blog, Love it though
Oh wow, yes. Love your post, more detailed and structured. Bookmarked. Glad I didn't see it first, it might have scared me off from writing my first post :)
Great tips, Nick! I also try to add code coverage, CI, and documentation badges to any of my serious projects.
Bookmarked!
Indeed, a well designed Readme is necessary for an open source software. To go further, here is a well-known list of awesome readme: github.com/matiassingers/awesome-r...
Some comments may only be visible to logged-in visitors. Sign in to view all comments.