It’s a popular recommendation when starting to code to document your journey. It allows us to showcase not only what we’ve been working on but also the progression and skills we've acquired along the way.
However, an aspect often overlooked is the importance of documenting the actual work itself.
I've encountered countless GitHub repositories where the README file is nothing more than a couple of lines describing the project as "a to-do app built with JavaScript." I suppose that is better than nothing at all, but it's still a wasted opportunity.
I get it. It’s a tedious task to document what you’ve been doing, especially after coding for ages on a project you’re ready to leave behind. Plus there’s that new shiny project idea that you can’t wait to get stuck into, right?
The Benefits
Yet, the payoff from crafting good documentation is substantial, not just for you but for others too, and it might just give you that edge you’re looking for.
It acts as a reminder of the challenges you faced and the solutions you discovered.
It provides other developers, potential employers, or anyone curious a comprehensive view of your project.
It offers an opportunity for you to reflect and document your growth as a developer.
A Starting Point: The README Template
To make the writing process a little less daunting I’ve drafted a template you can grab from this repo.
Heres an example of it implemented in one of my projects.
This template is just a starting point that you can iterate on and personalise further with each project. Don't feel like you have to include everything in the template, add and remove sections as you see fit. This is just to give you some inspiration.
If you find it useful, consider giving it a ⭐ on GitHub!
Keep these considerations in mind
When you’re piecing together your README, imagine you’re explaining your project to three people: a fellow coder, a potential employer, and your future self.
Your goal is to make it so any of them, coming across your work for the first time, would get a solid grasp of what the project is all about. Avoid assuming they possess your level of familiarity with the project. Share your knowledge!
Moreover, think of your README as a valuable reference for your future self, a snapshot that captures not only what you built but also the hurdles you overcame and the achievements (or setbacks) you experienced.
Tips
Take Notes: While working on the project take brief notes on any challenges, ideas, or anything else that's relevant. It makes the task of writing the final README less daunting. I just keep mine in a simple .txt file in the project.
Get creative: Markdown formatting is relatively basic but that doesn't mean you can't add some style along the way. Consistent spacing, font sizing, and bullet points can really add some polish and structure to your documentation. Use this markdown cheatsheet for a quick reference.
Include Visuals: Screenshots and demo videos can showcase your work and improve understanding, giving readers a quick glimpse of what to expect from your project. I use Shots.so for creating mock-ups.
Watch your spelling and punctuation: Grammarly and ChatGPT exist for a reason. Use them.
Wrapping Up
Crafting a comprehensive README is more than just a documentation task; it's an opportunity to tell the story of your project in a way that is meaningful to you and others. I hope you found this post useful and now feel a bit better equipped to draft your next README. Thanks for reading!