Engineering
Living Documentation: who knows how your system works?
Living Documentation is documentation generated from your website, app or system itself, with checks that fail the moment it falls behind. A one-off £999, with no monthly fee. Ready in 10 working days.
What happens when the one person who knows your system leaves?
Most small firms with a custom website, app or booking system have one person who knows how it works. When that person is a freelancer who has moved on, every change starts with weeks of questions.
The usual answer is a document written once, at the end of the build. It is out of date the first time anything changes, and nothing tells you it is wrong.
The fix I use on GigXchange is simple: generate the documentation from the system itself, so it cannot disagree with it, and run a check that fails the moment the two drift apart.
How is this different from a wiki or a handover document?
A wiki written once is out of date by the next change, and nobody notices. Living Documentation is generated from the system and rebuilt on every change, and when it falls behind a check fails and names the fix.
| In the developer's head | A wiki written once | Living Documentation | |
|---|---|---|---|
| Written by | Nobody | Someone, once | Generated from the system |
| Stays current | Never written down | Until the next change | Rebuilt on every change |
| When it falls behind | You find out when they leave | Nobody notices | A check fails and names the fix |
| Why things are built that way | Gone with them | Sometimes | One decisions log |
| Handing it over | Weeks of questions | Out of date on day one | A map a new person can follow |
What does living documentation include?
Living Documentation gives you a map of every file, an index of every screen part and who uses it, a feature index, a jobs list, staleness checks, a decisions log, a traps log and an hour-long handover tour.
- 01
A map of every file
Every file in your system with a one-line description taken from the file itself, not typed into a list.
- 02
A parts index
Every screen part on your site or app, what it is for and which pages use it - so nobody builds a second copy.
- 03
A feature index
What the product does, feature by feature, with each one's status and the pages it owns.
- 04
A jobs list
Every scheduled job, what it does and when it runs.
- 05
Staleness checks
A check for each index that fails when it falls behind and prints the one command that fixes it.
- 06
A decisions log
One place for why things are built the way they are, so the next person does not undo a choice for a reason they never saw.
- 07
A traps log
One place for the mistakes already paid for, written so they are not paid for twice.
- 08
A handover tour
An hour on a call walking you, or your next developer, through where everything lives.
What documents does living documentation produce?
A Living Documentation set lives in one docs folder: the file map, the parts and feature indexes, the jobs list and the two logs, each with a check that says ok or FAIL and the fix. Here is a sample.
docs/
- REPO-MAP.md - every file and what it does
- COMPONENT-INDEX.md - every screen part and who uses it
- FEATURE-INDEX.md - what the product does, spec by spec
- JOBS.md - every scheduled job and when it runs
- DECISIONS.md - why things are the way they are
- GOTCHAS.md - the traps we paid for once
- GUARD-REGISTER.md - every safety check and what it protects
- check: repo map is current - ok
- check: component index is current - FAIL, run the fix
- 145feature specs in a generated index
- 755screen parts indexed with who uses them
- 248decisions in one log
Source GigXchange's own figures, as of 25 October 2026
How long does it take to document a system?
Living Documentation takes ten working days: two to survey the system, four to build and run the generators, two to wire the staleness checks and start both logs, and two for the handover.
- 01
Days 1-2
Survey
I read your system and list what exists: files, screens, features, jobs and the documents you already have.
- 02
Days 3-6
Generate
The generators built and run, so each index comes from the system itself.
- 03
Days 7-8
Check
Staleness checks wired into your build, plus the decisions and traps logs started from what I found.
- 04
Days 9-10
Hand over
A walkthrough for you or your developer, and a one-page guide to keeping it current.
Does your business need living documentation?
Living Documentation suits a business with a custom website, app or system that one person, or nobody, fully understands - especially if you plan to hire, hand over or sell. It is the wrong buy for a template site you never change.
A good fit if
- You have a custom website, app or system
- One person (or nobody) knows how it all works
- You plan to hire, hand over or sell one day
Not for you if
- Your site is a standard template you never change
- You have no access to the code or the hosting
- You want a user manual for customers - that is a help centre
Questions
07Asked and answered
Living documentation is written by scripts that read your system, not by a person typing lists. Each file, screen part, feature and scheduled job describes itself, and the scripts gather those descriptions into indexes. A check then compares the indexes with the system and fails when they disagree. On GigXchange this keeps 145 feature specs and 755 screen parts indexed, and this website's own file map is generated the same way.
Four generated indexes and two logs. The indexes are a map of every file, every screen part and who uses it, every feature with its status, and every scheduled job. The logs are decisions (why things are built the way they are) and traps (mistakes already made once). If you also want every business document mapped - contracts, policies, finance - that is the Knowledge Index, which pairs well with this.
No - the indexes are plain tables written in plain English, readable by anyone who can open a document. The scripts and checks are for whoever works on the system, so a developer or an AI coding tool keeps them running. For you, the useful bits are the feature index, which answers "what does our system do?", and the decisions log, which answers "why is it like that?" without ringing anyone.
A check fails and prints the single command that brings it back in line. You decide which checks block a release and which only warn. At GigXchange the docs and feature index checks warn rather than block, because stopping a release over a markdown table taught people to ignore the warnings. The checks run inside the release process, so if you have one already, the Deployment Pipeline is where they slot in.
The £999 is one-off and covers the survey, the generators, the staleness checks, the first entries in both logs and a handover walkthrough. There is no monthly fee. The scripts live inside your own system, so they keep working whether or not you ever hire me again. If you add a big new area later, such as a mobile app, extending the generators to cover it is quoted as a small job.
Yes - it is one of the main reasons to do it. A buyer, an investor or a new developer will ask how the system works and what it depends on. With living documentation the answer is a set of current indexes and a log of every significant decision, rather than a week of calls. It also pairs with an Incident & Continuity Plan, which covers what to do if the system or its keeper suddenly is not there.
Yes, and that is often where it helps most. Code written fast by an agency or an AI coding tool tends to work but explain nothing. I add a one-line description to each file where none exists, then the generators take over. If the survey finds deeper problems, such as a database open to the public, I will tell you; the Database Security Audit is the fix for that.
Yes, read access to the code for the survey, and the ability to add the scripts at the end - nothing more. I never need customer data, payment accounts or passwords, and the generators skip files that hold secrets, so keys never end up in a document. Everything I add is in your system, under your name, and you can remove it with one change if you ever want to.