We already have documentation. Do you rewrite it or fix it?

We find out which, and the answer usually surprises people. The first thing we do is follow your existing instructions on a clean machine and write down every point where they fail. That list tells you honestly whether you have a document with gaps or a document that has quietly stopped describing the software. Tidying prose is cheap. Verification is where the work is.

Who keeps this up to date after you leave?

Your team, and the handover is designed so that it happens by default rather than by discipline. Documentation lives in the same repository as the code, in Markdown, and one line goes into the pull request checklist asking whether the change affects a document. Docs kept in a separate wiki that nobody passes on the way to shipping go stale, because nothing in the daily route to production ever forces anyone to open them.

Do you need access to the repository?

Yes, and ideally a way to run the system too. Documentation written from a specification rather than from the running software is where confident, wrong instructions come from. Read access to the code and an environment we can start is what makes the difference between description and verification.

We already have an OpenAPI file. Does that make this cheaper?

It makes the first half cheaper, because Redoc or Swagger UI will generate a reference page straight from it. It does not make the job small. The value is in what a generated page never contains — worked examples, what the error responses actually mean in practice, the sequence of calls a real integration makes, and the authentication step that trips everyone up.

Our engineers have no time to answer questions. Is that fatal?

No, but it changes the shape of it. Where something cannot be confirmed from the code we mark it inline as needing verification rather than writing a plausible sentence over the gap. You get the draft plus a short, specific list of questions that only a human can answer, which usually takes far less engineering time than being interviewed would.

Why is the range so wide?

Because a verified README and getting-started guide sits at one end and a full documentation site with information architecture, migration of existing pages, dozens of pages and hosting sits at the other. The largest single factor is whether we are verifying against running software or editing text you already have.

Consulting, Product & Talent

Technical documentation that people actually get through

API references, runbooks and onboarding guides where every command has been run on a clean machine before it was published.

From: $500–$8,000
Typical time: 2–6 weeks
Usually bought by: Dev teams

What this actually solves

Picture a small product company. Every new hire spends their first weeks consuming somebody senior's time, because nothing is written down and the knowledge transfer happens by interruption. The API has external customers, and a steady share of the support tickets are people asking how to get started rather than reporting anything broken. And when something falls over at night, exactly one person knows the sequence of steps that fixes it, and he is about to go on leave.

What is being bought here is time — specifically, expensive developer time that is currently spent explaining things to other people. That is a calculation you can actually run, and it is the only ground on which this service is worth what it costs. Good documentation is not a tidiness project. It is a way of stopping the same explanation from being given over and over by the most expensive people in the building.

The number that makes this concrete is time to first successful request — how long it takes someone starting from nothing to get one working call out of your system. It is worth measuring before any writing starts. Hand your current documentation to somebody who has never seen the product and start a clock. Whatever that number is, it is the honest justification for the project, and measuring it again at the end is how you find out whether the money did anything. We do this at the start because a number you collected yourself is more persuasive internally than any claim we could make.

What we do, and in what order

Scope. Which documents, for which readers, where they will be published, and who owns updating them afterwards. That last question is asked first because it changes how everything else is built. Half a day.
Install it ourselves, from zero, on a clean machine. Following your existing instructions exactly, writing down every single place we get stuck. That list of sticking points is the first draft of your getting-started guide, and it is usually the most valuable thing anyone hands you in the first week. It is also unfakeable — it can only be produced by someone genuinely starting from nothing. One to two days.
Audience map. A new internal developer, an external integrator, and an engineer on call at 2am are three different readers with three different needs, and one document serving all of them serves none of them. We decide which documents exist and who each one is for. Half a day.
Information architecture, before a word is written. The full contents list, sorted into the four Diátaxis categories — tutorial for learning with exactly one guaranteed path, how-to for a specific task, reference for complete and dry detail, explanation for why it was built this way. You approve the list before drafting starts, which is far cheaper than reorganising a finished set of pages. One day.
Draft from the source. Written inside the repository against the actual code, not from a description of it. Every command, config value, environment variable, endpoint and error message is traced to the file it comes from. Where something is believed but cannot be confirmed, it is marked inline as needing verification rather than covered with a confident sentence. Three days to two weeks depending on scope.
Run every command in the document. Copy it out of the draft, paste it into a fresh terminal, run it, and record the real output. If it does not run, the document is wrong and gets fixed, not explained away. This step is the whole difference between this and generated documentation. One to three days.
The silent test. The document goes to somebody who has never seen the system, and we sit with them and say nothing at all, however long they are stuck. Every place they stall is a defect. Talking them through it destroys the only measurement available. Half a day.
Publish and hand over. Docusaurus or MkDocs Material for a site, Redoc or Swagger UI for an OpenAPI reference, Mermaid for diagrams that live inside the Markdown, and screenshots dated because they go stale before the text does. Then docs-as-code — the documentation sits in the same repository as the code, with a line added to the pull request checklist asking whether this change makes a document wrong. Two to four days.

What moves the price

The range is $500–$8,000 over 2–6 weeks, and it is set by three things.

Which deliverables. A verified README and getting-started guide is the smallest useful piece. An API reference with hand-written examples and real error behaviour is larger. Three to five runbooks written for two in the morning, a full onboarding guide, or an entire documentation site with existing pages migrated into a new structure each move it up substantially.

Whether we build and host the site. Publishing to a documentation site with navigation, search, versioning and a deployment pipeline is a separate piece of work from delivering Markdown into your repository, even though the words are the same words.

Verification versus tidying, which dominates everything else. Cleaning up text you already have is one job. Running the system, executing every command, checking every parameter against the code and re-testing after fixes is a substantially larger job. It is also the only version worth buying, because it is the part that makes the document true.

What usually goes wrong

It is drafted with AI and shipped without a single command being run. This is now the most common failure in the whole discipline, and it fails in a specific and brutal way. The document reads beautifully. The reader reaches step three, runs the command, gets an error, and the entire thing is dead in that instant — because unlike most writing, the promise of documentation is falsifiable. It said this would work and it did not. Nothing in the rest of the document will be trusted afterwards. The defence is mechanical rather than clever, which is why it works. Every command in the document goes onto a numbered checklist and gets ticked off by a human who ran it.

A gap gets covered with a confident sentence. Language models do not leave holes. Asked to document a system, they will describe an endpoint that does not exist, in exactly the tone of the endpoints that do, and there is no stylistic tell to catch it. An honest marker saying this needs checking and who to ask is useful to everyone. A plausible invention is worse than a blank page, because a blank page does not cost the reader an afternoon. The rule in drafting is that anything not traceable to a file is flagged, never smoothed.

Everything ends up on one page. A tutorial, a complete reference and a troubleshooting section, merged into a single long document, is where most documentation written by a busy engineering team ends up. It looks comprehensive and it is unusable — the newcomer looking for one guaranteed path is served a table of every parameter, and the experienced engineer looking up a parameter has to scroll through a beginner's walkthrough to reach it. The four Diátaxis categories exist precisely to prevent this, and keeping them apart is more of the value in this service than the quality of any individual sentence.

See where the site stands before you brief anyone.

If the site is already live, start from what it scores rather than from a guess. The audit reports what it checked, what it found, and — the part most tools leave out — what it could not check, and why.

See the website audit Talk about this work

Questions people ask before they commit.

We already have documentation. Do you rewrite it or fix it?: We find out which, and the answer usually surprises people. The first thing we do is follow your existing instructions on a clean machine and write down every point where they fail. That list tells you honestly whether you have a document with gaps or a document that has quietly stopped describing the software. Tidying prose is cheap. Verification is where the work is.
Who keeps this up to date after you leave?: Your team, and the handover is designed so that it happens by default rather than by discipline. Documentation lives in the same repository as the code, in Markdown, and one line goes into the pull request checklist asking whether the change affects a document. Docs kept in a separate wiki that nobody passes on the way to shipping go stale, because nothing in the daily route to production ever forces anyone to open them.
Do you need access to the repository?: Yes, and ideally a way to run the system too. Documentation written from a specification rather than from the running software is where confident, wrong instructions come from. Read access to the code and an environment we can start is what makes the difference between description and verification.
We already have an OpenAPI file. Does that make this cheaper?: It makes the first half cheaper, because Redoc or Swagger UI will generate a reference page straight from it. It does not make the job small. The value is in what a generated page never contains — worked examples, what the error responses actually mean in practice, the sequence of calls a real integration makes, and the authentication step that trips everyone up.
Our engineers have no time to answer questions. Is that fatal?: No, but it changes the shape of it. Where something cannot be confirmed from the code we mark it inline as needing verification rather than writing a plausible sentence over the gap. You get the draft plus a short, specific list of questions that only a human can answer, which usually takes far less engineering time than being interviewed would.
Why is the range so wide?: Because a verified README and getting-started guide sits at one end and a full documentation site with information architecture, migration of existing pages, dozens of pages and hosting sits at the other. The largest single factor is whether we are verifying against running software or editing text you already have.

Often taken together.

Start with the brief, not the invoice.

Send what you are trying to achieve. You get a written scope, a price and a date — or an honest “this is not the right service for that”.

Talk about Technical documentation All Consulting, Product & Talent services