The docs your launch can’t ship without

"Are we gonna look like buffoons if we try to push something out and there is no documentation?" A business development lead at a hardware company asked us that on a discovery call a few weeks before his team's product was scheduled for release. His team had detailed engineering specs, but nothing that a customer could follow.

On a self-serve or partner launch, documentation is the onboarding experience. Gaps engineers smooth over during enterprise customer setup become problems general customers hit when they try the product.

In the final weeks before launch, engineers have little time to document what they know. The hardware company's business development lead told us his company's engineers describe the product "at the transistor level," while customers want to know how to use what they've paid for.

What must ship at launch

Before choosing pages, agree which reader to serve first and what that reader needs to accomplish. For a launch, the docs for that reader need to cover five things.

• Access, including accounts, credentials, and permissions
• The first successful task, written as steps a customer can run exactly as written
• Prerequisites, including older systems the new product still depends on
• Known limitations, stated plainly
• Recovery from the errors customers are likely to hit

Google's documentation guide argues that "a small set of fresh and accurate docs is better than a large assembly of 'documentation' in various states of disrepair." Our rule on launch work is to document the current state, never the future or the past. During an API migration, the current state can include an older endpoint the new product still requires, even when the plan is to show only new APIs on the new portal. Leave it out, and partners who can't finish setup will come back asking why the documented flow doesn't work.

Put accuracy ahead of coverage

When you don't have time for everything, a missing page costs less than a wrong one.

A customer who can’t find a page knows to ask for help. A customer who follows a wrong instruction doesn’t know anything is wrong until something breaks, and then has a reason to doubt every page after it.

Redesigning a desktop app can mean a new help center article for every button and menu item. Fix each published article for the current version first, and add the rarer workflows once launch pressure eases.

Accuracy takes product access. Writers working from specs and old pages can produce something that reads well and describes the previous version, so we ask for a working environment before we write a launch page.

Test what you publish against the product

Rust builds documentation testing into its tooling. Its documentation generator, rustdoc, can run the code examples in the docs as tests, which, in the Rust project's words, "makes sure that examples within your documentation are up to date and working."

We apply the same idea to launch docs. On API launches, our engineers write the quick start as complete working code, build the provider’s sandbox test cases into it as runnable tests, and include those tests in the tutorial, so a partner’s first experience is copy and paste instead of writing the integration from a list of requirements. Once the example works, show readers what to change for their own task and where to look next.

Running the examples also turns up questions the spec doesn't answer, such as which fields a request actually needs or how a partner gets and rotates keys. We send those questions to the product team with steps to reproduce them, while there's still time to answer before launch.

Put review time on the launch plan

Kubernetes treats docs as a release deliverable with its own deadlines. Its release timeline has feature owners open a placeholder docs pull request about three and a half weeks before release. The docs then need to be ready for review about two weeks out, with review finished about a week before release. GitLab builds the same expectation into its Definition of Done, which lists updated end-user documentation as part of finishing development work.

Enterprise launches can add reviewers outside engineering. On our enterprise projects, compliance review and the team that runs a developer portal can each take a week or more after the writing is finished, so each review needs an owner and a date on the launch plan.

Some decisions belong to product, such as whether an API is ready to document. Docs that depend on one of those decisions can't settle until product makes it, so the decision needs a date on the plan too.

When no one owns the docs

When a team has one writer or none, launch docs fall to the engineers and product managers who are busy shipping. In The role AI can’t fill, Tippi Fifestarr describes the documentation engineer as the role that “gets cut first.”

At a DeFi trading platform we worked with, the engineer responsible for the docs was also planning the launch infrastructure. We took over the docs. Our documentation engineer built a TypeScript quick start and organized the pages around what traders and developers each needed to do.

Short-staffed teams can hire a technical writer or outsource technical writing for the launch window. Whoever does the work has to learn the product well enough to test it, and quickly. Writers who only polish what engineers hand them can't check whether a step works.

Our engineers learn the product during a brief discovery, and clients have a draft or a prioritized backlog within two weeks. For software releases and API launches, we hand over the docs with a style guide and a maintenance guide, so in-house writers can own them after launch.

The hardware company asked the right question with weeks still left before release. A team that focuses its docs on what customers need on day one and keeps those pages accurate can ship on date without looking unprepared.

We scope documentation systems for teams managing complex, fast-moving products. Start with a discovery call.