Theo Marsh says his longest-running side project began with almost no documentation, while a more carefully documented project died within a couple of months. His explanation is not that bad READMEs make projects last; it is that he documented one project before he knew whether anyone wanted it, and waited to document the other until its shape had settled.
What happened to Marsh’s two projects
| Project | When documentation appeared | What Marsh says happened |
|---|---|---|
| The carefully documented project | Before it had a real user; it had a README, architecture document, and roadmap. | Marsh says it died within a couple of months. He later felt bad about deleting documentation for a project that had not found an audience. |
| The scrappier project | It started without documentation because Marsh used it every day. Documentation came months later, after the product’s shape had changed three or four times and then stabilized. | It became his longest-running project, according to Marsh. |
That contrast is an account of one developer’s experience, not a controlled comparison. It cannot show that a weak README helped the second project survive or that documentation contributed to the first project’s end.
As an Amazon Associate I earn from qualifying purchases.
Why write-ups can get ahead of a project
Marsh describes writing the first project’s README, architecture document, and roadmap before it had a real user as a way to feel productive while avoiding a harder question: whether anybody wanted the project. When the answer turned out to be no, the documents felt like an investment he had to feel bad about abandoning.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallThe second project had a different starting point: Marsh was building for his own daily use. By the time other people used it, its code and product shape had changed several times. Documentation written at the outset, he argues, would have described a version that soon became inaccurate.
When to write documentation for a side project
Marsh’s practical idea is to let decisions meet real use and revision before treating them as settled explanations. He says he now waits to explain a decision until it has “survived being wrong at least once.” That is his personal practice, not a rule proven to work for every project.
A useful distinction is between notes that help you build today and documentation that claims to explain how a project works. Early notes can be provisional; a durable README or architecture guide is more useful when it reflects decisions that have endured actual use. If you do write early documentation, mark assumptions and update or remove them as the project changes.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Documentation still matters when a project matures
Marsh explicitly does not argue that documentation is bad. A mature project needs it: users and contributors need a reliable account of what the software does and how to work with it. His point is about timing. Plans written before there is evidence of demand or a stable product shape may preserve intentions rather than describe a working project.
Marsh’s essay, “Why my longest-running side project is the one with the worst README,” appeared on DEV Community under his name; the search result shows “Sep 22” but does not establish a year. The page could not be fetched, so the anecdotal details here are attributed to the available account rather than presented as independently verified findings.
Quick Recap
Best Value
Rank #3
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
