From 2024 to early 2026, I built a lot of projects, and I pushed them to Github the way many developers do: commit, push, move on. There was no README, no screenshot and no explanation. My profile was a list of repository names that only I could understand.
I am a first-year informatics student in Bogor, Indonesia and a full stack developer working with Laravel, Node.js and Python. This article is about why I finally decided to clean up my repositories, what I did, and what I learned along the way.
The Problem: A Repository Without a README Is a Locked Room
When someone opens a repository, they want an answer to one question: what does this project do? If the answer is not on the first screen, most people will not dig through folders to find it. That includes recruiters and hiring managers, who often review many profiles in a short time.
I had the skills, but my profile did not show them. Real projects, including client work and systems with real business logic, were sitting there with nothing to explain them.
I was proud of everything I had built, and I honestly believed my work was already professional. Then a friend got a job, and it made me look at my Github profile the way a recruiter would. When I actually checked it, I saw that my profile was empty: no explanations, no screenshots, and nothing that told a stranger what my projects could do. There was still a lot missing.
I realized that a good README is not decoration. It is the difference between a repository that gets ignored and one that makes someone curious enough to look closer.
Step 1: Choose a Few Repositories, Not All of Them
My first instinct was to fix everything at once. That is a trap, because it takes weeks and nothing gets finished. Instead, I picked four repositories that show different skills:
| Repository | What it does | What it shows |
|---|---|---|
business-registry-data-pipeline |
Selenium-based scraper that extracts and validates company data from Indonesia’s business registry, then saves it to MySQL with upsert logic and JSON export | Data extraction, validation, and persistence |
pos-cashier-loyalty-system |
Full-featured POS system with role-based access, inventory synchronization, and loyalty points | Business logic and access control |
hidayat-news |
News publishing CMS built with CodeIgniter 3, with content management, role-based access, login analytics, and proxy/VPN detection | Backend and CMS development |
blockwave-design |
Static frontend prototype built during a freelance engagement with Blockwave Studios | Frontend and client work |
Together, they cover data engineering, business logic, content management and frontend work. I pinned all four to my profile so they are the first thing a visitor sees.
Step 2: Write the README for a Stranger
I wrote each README as if the reader had never heard of me or the project. I aimed for this structure:
- One-sentence description. What it is and who it is for.
- Screenshots or a short demo. People trust what they can see.
- Key features. A short list, not a wall of text.
- Tech stack. It helps recruiters match your skills to a role.
- Getting started. Install and run steps that actually work.
- Project status. Is it finished, in progress, or archived?
A good README does more than list features. It explains decisions: why the scraper uses upsert logic, or why the POS system needs role-based access. Writing that down forced me to understand my own projects better than when I first built them.
Step 3: Check the Details Beyond the README
A polished README can hide careless mistakes. Before calling a repository finished, check these points:
- Description and topics. Fill them in on the repository sidebar so the project can be found.
-
Environment files. Commit a
.env.example, never the real.env. - Commit history. Make sure no passwords, API keys, or tokens were ever committed. Deleting a file in a new commit does not remove it from history.
- Client permission. If a project came from client work, confirm you are allowed to show it, or replace sensitive data with dummy data.
- License and structure. Add a license and keep the folder structure clear.
The Result
Before, a visitor saw only file and folder names and had to guess what each project did. Now, each pinned repository explains its purpose, its main features, and its tech stack, so a visitor can understand it without opening a single source file.
What I Learned
- Do less, but finish it. Four complete repositories are better than twenty abandoned ones.
- Write for the reader, not for yourself. Assume they have thirty seconds and no context.
- Documentation is part of the project. A project is not finished until someone else can understand and run it.
- Re-reading your own code is a security review. While writing the READMEs, I went back through my code and found sensitive information in several projects. I removed it and cleaned up those repositories. If a secret was ever committed, treat it as exposed and rotate it, because deleting it from the latest commit does not remove it from the history.
What’s Next
I still have older repositories to review. For each one, I plan to decide whether to improve it, make it private, or archive it. My next article will cover how I handled Cloudflare in business-registry-data-pipeline, where the scraper drives a real browser with Selenium and waits out the verification challenge.
If you have a similar backlog, start with just one repository this week. How do you decide which projects to showcase? I would love to hear your approach in the comments.



Top comments (0)