"Programs must be written for people to read, and only incidentally for machines to execute." — Donald Knuth
You finally finish your project.
After hours of debugging, Stack Overflow tabs, and one bug after another, it works. You push it to GitHub, close your laptop, and move on.
A few months later, you come back to add a new feature.
You open the repository. Dozens of files. A few variables with names that made perfect sense at the time. Now they don't. You scroll through your own code, trying to remember why you chose this approach over that one.
Eventually you ask the question almost every developer asks:
"Who wrote this?"
You did.
If that sounds familiar, you've already discovered why documentation matters. You don't write it for your teacher, your manager, or your teammates. You write it for your future self — the one who's forgotten everything you know right now.
Photo by Alicia Christin Gerald on Unsplash
The Biggest Myth About Documentation
Most developers treat documentation as something you write after a project is done. That mindset is exactly how projects end up with no documentation at all — "later" rarely comes.
Documentation isn't the final chapter. It's part of building the thing.
You wouldn't wait until a house is finished to draw the blueprint — the blueprint guides the construction. Documentation does the same job for code: it records your decisions and explains your reasoning as you go, not after the fact.
GitHub's own guidance backs this up: a README should explain what your project does, why it exists, how to get started, where to get help, and who maintains it — because for most visitors, it's the first thing they see and it shapes their whole impression of the project.
What Documentation Actually Is
Say "documentation" and people picture a massive technical manual. Sometimes it is that. More often, it's much smaller:
- A README
- Installation instructions
- A comment explaining tricky logic
- A troubleshooting note
- A changelog
Documentation is just information that helps someone understand your software — where "someone" might be you in six months, a teammate, a contributor, or a recruiter skimming your GitHub. Good documentation answers questions before people have to ask them.
Why Most of Us Skip It And What It Costs
Documentation isn't exciting. Watching your app finally run is exciting. Writing a README is not. So beginners tell themselves "I'll document it later," and later rarely comes.
By the time you return to the project, you've forgotten why you chose that library, what a function actually returns, which environment variables it needs, and which command fixed yesterday's bug. You end up solving the same problem twice — time you could've spent building something new.
GitHub Star Monica Powell calls personal documentation a "second brain": instead of re-searching for the same answer every time, you write it down once, in a way that makes sense to you, and reuse it. That alone is worth the five minutes it takes.
The Hidden Cost of Poor Documentation
Picture two repositories.
Repo A:
project/
├── README.md
├── src/
├── docs/
└── package.json
The README explains what it does, how to install it, how to run it, how to contribute. You clone it and you're running the project in five minutes.
Repo B:
project/
├── src/
└── package.json
That's it. No instructions, no examples, nothing.
Which one feels more trustworthy? Which one would you actually contribute to?
Researchers who studied thousands of GitHub repositories found that the README is often what shapes a developer's first impression of a project and whether they can figure out how to use it at all. Documentation builds trust before anyone even opens your code.
It Also Makes You a Better Developer
It's easy to assume documentation is purely for other people. It isn't. Writing it forces you to answer questions like:
- What problem does this actually solve?
- Why this approach, and not another?
- What am I assuming the reader already knows?
If you can't explain your project clearly, you probably don't understand it as well as you think you do. Writing it down is a forcing function for organizing your own thinking.
Good Documentation Is Short, Not Exhaustive
The other common misconception: good documentation means a lot of documentation. It doesn't. It means the right information.
GitHub's documentation team recommends writing in plain language, staying concise, and structuring content so people can scan for what they need — not covering every possible edge case. One clear paragraph or a single code example often teaches more than three pages of prose. Quantity isn't the goal; clarity is.
A Habit You Can Start Today
Every time you solve a problem that takes more than five minutes, write down four things:
## Problem
The application crashed after deployment.
## Cause
The environment variables weren't configured.
## Solution
Added the missing variables to the production environment.
## Prevention
Add an environment variable checklist before deployment.
That's it. That's documentation. Do this consistently and you'll build a personal knowledge base that gets more valuable every month — your own second brain, one entry at a time.
Beyond the README
A README is the entry point — both GitHub's and Google's engineering style guides treat it that way — but it's not the whole picture. Documentation also lives in:
- Code comments
- Architecture diagrams
- API references
- Troubleshooting guides
- Changelogs and design decisions
Each one saves someone (probably future you) from having to reverse engineer your reasoning from scratch.
Key Takeaways
- Documentation is written for people, not computers.
- Your future self is usually your first reader.
- Small notes written consistently beat one giant document written at the end.
- A good README shapes first impressions and builds trust before anyone reads your code.
- Documentation is part of development — not something that happens after it.
Next time you finish a piece of code, don't just ask "is it done?" Ask: "Would someone else know how to use this?"
If the answer is no, your next line shouldn't be code. It should be documentation.
In Part 2, we'll build your first documentation habits; the small routines experienced developers follow without even thinking about them.
Top comments (0)