We are a documentation agency. This is a guide to hiring one, including the signals that should make you walk away from us specifically.

If that sounds like a risky thing to publish, it is. We're publishing it because the alternative, letting the market keep buying on vibes, is worse for everyone in it, including us. Agencies that can't be evaluated against real criteria compete on founder charm and Figma screenshots. Buyers spend six figures and end up with a repainted site and the same support load. Then the whole category earns a reputation it deserves.

So here is the guide we would hand a buyer who had never hired a docs agency before, written as if we were not one of the vendors on their shortlist.

The market grew up faster than the criteria#

Documentation work used to be a line item inside a product org or a contract gig for a freelance writer. In the last three years it has become a category: agencies with named methodologies, retainers, retrieval audits, and pricing that matches a mid-tier design shop. The supply caught up. The buyer criteria did not.

Most RFPs we see still screen on three things: portfolio aesthetics, the founder's warmth on the intro call, and a monthly number. None of those predict whether the engagement will reduce support tickets, improve retrieval accuracy, or make your product answerable by an agent six months from now. They predict whether you will enjoy the kickoff.

The signals below are the ones that actually predict delivery. The anti-signals are the ones that predict a reheated portfolio piece. We end with the part where we apply all of it to ourselves.

Six signals to look for#

1. A published methodology you can audit.

A serious agency has written down how they work, in public, in enough detail that you can hold them to it mid-engagement. Articles, frameworks, a playbook on their site, conference talks with the slides still online. Not a sales deck delivered under NDA after the second call.

The test is whether you can read the methodology on Tuesday, use it to challenge a decision on Thursday, and get a coherent answer. An agency whose method is "we'll figure it out together" is selling bespoke consulting at agency rates, with none of the accountability that a named method creates.

2. Measurement they bring to you, unprompted.

Ask how you will know the engagement worked. A serious answer includes a pre-committed number: retrieval-audit score at month three, support-ticket volume against a baseline, time-to-first-successful-query for new users, activation lift on a defined funnel step. The agency picks the metric before the contract is signed and agrees to report against it.

A weak answer is "the docs will look better" or "your team will love using it." Those are feelings. Feelings are not a deliverable you can hold anyone to.

3. References at the practitioner level, not just the executive level.

Every agency will hand you the VP of Engineering who signed the check. The VP will say the engagement went well because the VP's job is not to remember whether deadlines slipped. Ask for the docs engineer, the senior technical writer, or the DevRel lead who lived inside the work. Ask them three things: Did the agency ship on the dates they committed to? Did they push back on a bad spec? Is the codebase and content they left behind something you can maintain without them?

Practitioners will tell you. Executives will tell you what they remember from the closeout deck.

4. A willingness to turn work down.

Ask directly: "When did you last decline a prospect, and why?" An agency with a real method has a real set of engagements it is bad at, and can describe one without flinching. An agency that says every deal is a good fit is either lying or is in the business of taking checks rather than delivering outcomes.

We published a separate post about when AI-ready documentation is the wrong investment. If the agency you're evaluating can't articulate a version of that post for their own practice, that is information.

5. A named practitioner on the statement of work.

Who, specifically, is doing the work? Not "our senior team" or "a dedicated pod." A name, a title, a LinkedIn, and a commitment in writing. On most bad engagements, the partner who sold the deal disappears after kickoff and the work lands with someone the buyer has never met. Naming the lead in the SOW, with a clause that triggers a conversation if they come off the project, is the simplest way to prevent that.

6. A clean handoff you own at the end.

At month six, who owns the content pipeline, the style guide, the templates, the retrieval configuration, and the review process? The right answer is: you do, and here is the handoff document that makes that real. The wrong answer is that the agency retains the dependency, through a proprietary CMS, a closed retrieval stack you can't inspect, or a tooling layer you have to keep paying for to keep the lights on.

Ownership at handoff is the single biggest predictor of whether the work survives the next reorg.

Six signals to walk away from#

1. The pitch leads with their AI.

If the first half of the conversation is about their proprietary AI-powered retrieval engine, their in-house agent, or their custom LLM pipeline, they are selling the tool. The tool is almost certainly behind whatever frontier model shipped last quarter, and it will be further behind by the time the engagement closes. An agency's job is to make your documentation work with whatever model your customers are actually using, not to lock you to an internal stack that has to be maintained by six people in a Slack channel.

2. No pushback on your brief.

You sent a bad brief. Every brief is bad the first time. If the agency nodded, priced it, and returned a proposal that echoes your words back in a nicer font, they are order-takers. You want the agency that reads the brief, tells you two things are wrong with it, and quotes against the corrected version. An agency that cannot push back during the sales cycle will not push back when you are about to ship something that will embarrass you.

3. The portfolio is aesthetics, not outcomes.

Beautiful docs sites. Clean typography. No numbers. No before-and-after metric. No mention of what changed for the business that hired them. Aesthetics are cheap to produce and almost impossible to connect to a result. Outcomes are expensive to produce and easy to verify. A portfolio without any outcomes in it is telling you which one the agency is optimizing for.

4. Pricing anchored to time, not to outcome.

"We charge $X per month for Y hours of a senior writer." That is body-shop pricing. It sells access to people, not solutions to problems, and it transfers all the risk to you. Good agencies price to outcomes where they can: a retrieval audit is a fixed fee for the audit and its remediation plan, not a fee for a writer's month. Time-based pricing is not automatically disqualifying, especially on true retainers for ongoing maintenance, but if the entire price sheet is hours, you are buying contractors with a logo.

5. No answer for your industry's failure modes.

Healthcare docs fail when compliance language crowds out task orientation. Fintech docs fail when regulatory copy is copy-pasted across products that behave differently. Protocol and infrastructure docs fail when the reference is current but the conceptual layer is three releases behind. SaaS docs fail when onboarding and reference live in different tools under different owners. An agency that pitches you with "we'll improve IA, reduce drift, and make your docs AI-ready," with no specifics about where your category breaks, has not done the work of specializing. You are paying for their learning curve.

6. No plan for drift.

Every engagement produces clean documentation on the day it ships. The real question is what the doc set looks like at month six, after a release, a reorg, and two new product lines. An agency without a stated answer, whether that is an ongoing retainer, a clear handoff to your team with maintenance tooling, or a scheduled re-audit cadence, is selling you a problem that will be six months old by the time you notice it.

The questions to ask on the evaluation call#

Use these verbatim. Short, specific, hard to deflect.

"What kind of project do you decline, and when did you last decline one?"
"Walk me through an engagement where you missed the mark, and what you changed afterward."
"What number, measured how, will tell us this is working at month three?"
"Who, by name, is leading this engagement, and what happens if they leave?"
"What exactly do we own when the engagement ends, and what, if anything, stays with you?"
"If we do nothing, what will our docs look like in six months, and why?"

If an agency cannot answer any of these crisply, inside the call, without a follow-up email, they are not the right partner. This includes us.

The part where we apply this to ourselves#

We would be cowards to publish the preceding sections and not run the same screen on DevDocs. Here is where we pass, where we are mid, and where a buyer could legitimately hold us to account.

Published methodology. We pass. Our approach is written down on this site, including the parts that are uncomfortable to commit to in public. Hold us to it.

Measurement we bring to you. We pass on audits and remediation engagements, where we commit to a retrieval score or a ticket-volume delta before the contract is signed. We are weaker on long-tail content retainers, where we have historically reported on output (pages shipped, reviews completed) rather than outcome. We are rebuilding those retainer reports around a smaller number of outcome metrics. Today, if you sign a retainer with us, ask for the outcome metric in writing and do not accept output metrics as a substitute.

Practitioner-level references. We pass, with a caveat. We will connect you to the writer or engineer who did the work, not only the executive who signed. The caveat is that our reference pool is smaller than agencies twice our age, and a buyer who needs fifteen references across five verticals should know that up front.

Willingness to turn work down. We pass. We have declined engagements in the last year where the buyer's real problem was product, org structure, or a pricing page, not documentation. We have also taken engagements we should have declined, and we can describe those too if you ask.

Named practitioner on the SOW. We pass on new engagements. Older SOWs in our backlog named "the DevDocs team" rather than a specific lead. If you are evaluating us against an older case study, ask who actually ran the work and whether they are still here.

Clean handoff and ownership. This is our weakest area and we will say so plainly. Our handoffs are strong on engagements where we scoped handoff as a deliverable from day one. They are thinner on engagements where handoff was treated as a closeout task. We are standardizing a handoff artifact across every engagement type, including the maintenance runbook and the tooling inventory, and we are not done. If you sign with us today, put the handoff artifact in the SOW as a named deliverable with its own acceptance criteria. Do not take our word that it will be there.

Pricing. Mixed. Our audit and remediation work is outcome-priced. Some of our retainers are still time-priced because the work is genuinely open-ended and we have not found an honest way to price it to outcome yet. We are suspicious of agencies that claim to have solved this completely, and we are not going to pretend we have.

Industry depth. We are strongest in developer tools, infrastructure, and technical SaaS. We are credible in fintech. We are learning in healthcare and regulated life sciences, and a buyer in those categories should weight that heavily. If your failure modes live in a vertical we do not know cold, hire the specialist.

If you are evaluating us, run every item in this post against us, not just the ones where we look good. If we flinch on any of them, that is the signal.

Closing#

The most useful thing an agency can do for a maturing market is write the buyer's guide against itself. This is ours. Use it on your shortlist, including on the entry with our name on it. If a competitor writes a sharper version, we will link to it. If you use this list and walk away from us because of it, that is the system working.