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:
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
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.
Explain in 1-2 sentence what your project does. What can the users expect?
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?
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?
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?
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.
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.
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!