Do you need the original developers?

No. It helps when they're available, but the code, the database and the logs carry most of the answers. Where nobody knows why something works a certain way, I say so in the notes rather than guess.

Will you change the code?

Only to add tests, and occasionally to make the code testable in a small, safe way. Fixes and improvements go on a written list for you to decide on. Some clients have me do them next; some give the list to their own team.

What format is the documentation in?

Plain text files in the repo, mostly Markdown, with diagrams that live next to them. They're readable on GitHub, easy to update, and an AI assistant can read them too. If you'd rather have them in a wiki as well, that's easy.

How long does it take?

The first overview usually takes a week or two. Fuller documentation and tests depend on the size of the system. The assessment gives you a real estimate instead of a guess.

Which languages and frameworks do you work with?

I'm strongest in Ruby on Rails and Postgres, and I read most mainstream web stacks comfortably. If your system is in something I can't do justice to, I'll tell you during the assessment.

Who owns the documentation?

You do, along with the tests and everything else I produce. It lives in your repo and your accounts, and it's written so any future developer or freelancer can use it without me.

The App That Runs Your Business and Nobody Fully Understands. Here Is How to Get It Written Down

The system works. Nobody is sure why.

Your app has been running for years. Customers depend on it. It handles cases nobody remembers designing for, and it handles them correctly, most of the time. It got that way because smart people made careful decisions over a long stretch.

Then those people moved on. A developer left for another job. A contractor finished. The person who knew why the nightly import runs twice is now in a different department. What’s left is code, a few out-of-date wiki pages, and a growing reluctance to touch anything.

You feel it in small ways. Simple changes take weeks because everyone is afraid of side effects. New hires take months to become useful. One person is the only one who can deploy, and they’re getting tired of being on call.

None of this means the app is bad. Often it’s very good. It just isn’t written down, and there are no tests to tell you when a change breaks something.

What I do

I treat the running system as the source of truth and work backwards from it. The code, the database and the logs show what the app actually does, which is often different from what anyone believes it does.

A written system overview. In plain language: what the parts are, where the data lives, what talks to what, what runs on a schedule, and which outside services it depends on.
Diagrams of how data flows. How an order, a claim, a booking or whatever your core record is gets created, changed and reported on. One picture per critical flow.
Characterization tests. Tests that pin down what the code does today, not what it ought to do. They’re the safety net that makes the next change safe, and they often surface behaviour nobody knew about.
Runbooks for the jobs that currently live in one person’s head: deploying, restoring a backup, rerunning a failed import, rotating a key, onboarding a new developer.
Decision notes on the odd parts. When I find a strange workaround, I trace why it’s there and write it down, so nobody “cleans it up” and breaks a customer.
Instructions for AI assistants, so the next developer who opens the code with an AI tool gets accurate help instead of confident guesses about a system it has never seen.

I don’t rewrite the app while doing this. Understanding comes first. Any changes worth making go into a written list, ranked by risk, for you to decide on.

Figure 1. Recovering the spec. The running system is read, pinned down with tests, and written up so the knowledge stops depending on memory.

When your developer is leaving

If you’re a founder and your only developer has handed in notice, or a contract is ending, the clock matters. While they’re still around, I work with them: short recorded walkthroughs, their answers to the questions that the code can’t answer, a check of where every password and account lives. Their knowledge is the most valuable thing in the building for those few weeks, and I treat it that way.

After they leave, the documentation, tests and runbooks mean the next person, whether that’s a hire, a freelancer or me, starts from a written map instead of from scratch.

Why me

I spent seven years as a senior engineer on a multi-tenant B2B SaaS that grew from about $4M to $13M in annual revenue, and ran its roughly 1TB Postgres database. A lot of that job was understanding code written long before me, by people who weren’t there to ask. I also build and run a live product on my own, so I write documentation knowing I’ll be the one reading it at two in the morning. I write about some of that work on my writing page, including audit logs and zero-downtime migrations.

Take a business like this one

The business in this section is a composite of the kind of company I talk to, not a named client. The numbers are the shape of the problem, not a case study.

Picture a specialty insurance broker whose quoting and policy system was built in-house nine years ago. It’s a web app on an older framework version with a Postgres database. The two developers who built it have left. A contractor keeps it running, but only one person can deploy, and nobody can explain why certain quotes get a manual-review flag. There are almost no tests. The business wants to add a new product line and nobody dares to start.

What I’d do for a business shaped like this:

First week: map it. Read the code and the schema, list every scheduled job and outside service, and produce a first system overview and a list of the riskiest unknowns.
Talk to whoever is left. The contractor, the underwriters who use it daily, anyone who remembers the original build. Each answer goes into the decision notes.
Trace the manual-review flag and the other mystery behaviours to their source in the code, and write down what triggers them.
Characterization tests around quoting and policy issue, the flows where a silent change would cost money.
Runbooks for deploys and restores, tested by having someone other than the contractor follow them.
The handoff pack. Overview, data-flow diagrams, runbooks, decision notes, AI-assistant instructions and a ranked list of recommended changes. The new product line can start from there.

The underwriters keep doing what only they can do: knowing which quotes are right and why.

What it costs

It starts with a small fixed-price assessment: a first system overview and a written list of the biggest risks and unknowns. You get something useful even if you stop there. The fuller documentation and test work is scoped from what the assessment finds. No retainer, and nothing you have to keep paying for to read your own docs.

What I need from you

Read access to the code, the database and the hosting. An hour or two with anyone who uses or remembers the system, and if a developer is leaving, as much of their time as you can get before they go. Then a person on your side who can tell me when the written spec doesn’t match how the business really works.

Your app works. I'll write down how, so it stops depending on memory.