Good documentation earns trust through a clear first impression, short paths to value, readable writing, and visual cues that help users orient themselves.
2
Documentation teams should organize content around the user's work, test pages with real users, and use examples instead of empty templates to guide engineers.
3
Documentation metrics are signals toward a product goal, with time to a user's first successful action often more useful than page views or time on page.
Summary
Dave Nunez explains how documentation affects a developer before they have learned a product's terminology. A page with a clear starting point, whitespace, diagrams, short code examples, and a scannable structure can build trust. A page full of dense text can make a user leave before trying the product. He describes the writing culture at Stripe, where documentation affected hiring, career ladders, release decisions, and executive reviews. He also recommends testing pages by watching users work through real tasks and asking what they took away. For documentation structure, he prefers an information architecture that follows the user's work, such as getting started, design, build, deploy, and manage. Metrics such as search terms, page ratings, support tickets, and time to first successful action help teams decide what to improve. Dave says AI products need a different approach because real-time, multimodal interfaces do not fit neatly with static documentation.
A documentation page has to earn trust before it teaches anything
Dave says developers often arrive at documentation already frustrated because they are blocked or have limited time to evaluate a product. A poor first impression includes no clear starting point, unfamiliar terminology, and a quick start that is mostly dense prose. A better page makes the task visible through a diagram, one sentence describing the outcome, or a few lines of code. The page does not need to solve every problem immediately. It needs to invite the user to continue. Dave also says writing should be clear and human-centered, rather than shaped mainly around translation tools or an exhaustive list of everything the product can do.
Whitespace and simple sentences help developers forage for information
Dave describes documentation reading as information foraging. Developers scan for useful pieces rather than reading every line from left to right, and eye-tracking studies he cites show an F-shaped pattern. Whitespace makes a page approachable and scannable. Each sentence should mostly stand on its own, with clear sequencing between steps. He does not expect users to praise the docs. The practical goal is to avoid frustrating them. To review a page, Dave recommends leaving it for a day and returning with fresh eyes. A coworker can also read it and explain the takeaways, which reveals whether the intended task or concept is clear.
Writing culture becomes real when leaders attach documentation to decisions
Dave says Stripe's writing culture appeared in hiring, engineering career ladders, and launch reviews. Staff engineers were expected to write strong design and architecture proposals, while documentation was included in release decisions. If a release was delayed because its docs were not ready, that showed the organization treated documentation as part of the product. For teams changing from the bottom up, he recommends assessing writing during hiring, including knowledge sharing in performance reviews, and bringing professional writers together across marketing, brand, support, and technical teams. Shared style guidance gives engineers a common standard instead of leaving every writer to invent one.
Annotated examples teach engineers more effectively than blank templates
Dave says a template with a few empty headings often leaves engineers unsure what to write. His team improved this by creating strong examples for each content type, such as an overview, quick start, and how-to guide. Annotations can explain why a section exists, but the complete example gives engineers something they can pattern-match against. It shows the expected structure, length, and level of detail. He also describes an internal, self-guided book for engineers that included templates, annotations, checklists, and an end-to-end process for creating documentation. He wishes he had started that resource at the beginning rather than building it over several years.
Documentation should follow the user's work instead of generic content categories
For a small product with a few features, Dave recommends starting with a short explanation of what the product is and why it matters, followed by a quick start that lets someone accomplish something in roughly 15 to 20 minutes, or 30 minutes at most. As the product grows, the information architecture should guide users through their actual work. Generic buckets such as overview, concepts, tutorials, and troubleshooting may describe content types, but developers often think in terms of getting started, designing, building, deploying, and maintaining. Dave says teams should identify the phases for their product and arrange the documentation around that sequence.
User research reveals friction that page analytics cannot explain
Dave recommends watching users work in a fresh browser while they try to complete a real task. Researchers should avoid directing them to a particular page at first, because users may begin with Google, Reddit, YouTube, or another route. Asking users to think out loud reveals how they interpret titles, search results, page layout, and navigation. Different users search and browse in different ways, so several sessions are needed. This process can expose pages with poor titles, buried information, or confusing paths. Dave also recommends testing a document with a coworker by asking what they took away, then iterating until the intended task or concept is clear.
Escape hatches keep users from getting trapped on the wrong documentation path
Dave describes escape hatches as callouts that acknowledge when a page may not fit the visitor's use case. Stripe had two Checkout paths with the same product name: a hosted, no-code form and a customizable, code-based option. A user could arrive at the wrong page through search without knowing the other path existed. The documentation therefore pointed users from one option to the other. Dave says this pattern applies whenever a product offers meaningful choices. A page can tell someone that another route exists and direct them there, instead of making the user conclude that the product does not support their needs.
Documentation metrics are signals, while successful user actions are closer to the goal
Dave has used page views, bounce rate, search queries, signups, and support-ticket deflection to evaluate documentation. He says these measures do not give a complete picture and can produce poor docs if teams optimize them in isolation. Page ratings can identify pages that need attention, while search terms reveal missing content and the vocabulary users actually use. At Stripe, the team measured the time to actions such as creating a first charge, subscription, or invoice. Dave treats these measures as signals toward the company's goal and the user's needs. Bounce rate, for example, has a different meaning for a password-reset page than for a product guide.
AI products require new ways to educate users because static docs do not match the interface
After leaving Stripe in July 2022, Dave began advising and investing in startups, then received inbound requests from AI-focused companies that had products but no way to educate users. He says the established SaaS documentation playbook does not transfer cleanly to products with real-time and multimodal interfaces. A user may interact with an AI product through an interface that changes during the session, while traditional documentation remains static. Dave's consulting work focuses on rethinking how information is presented for these products. He also says the field lacks the settled examples and practices that existed for SaaS, which is why he is working on new approaches.
"The documentation shouldn't be about solving all of their problems all at once and being perfect across the board. It should be like, how can you build that trust and keep getting them to go down that path?"Dave Nunez04:58
Who should watch
You own or maintain developer documentation and need practical ways to improve onboarding, navigation, or page quality.
Your engineering team produces documentation inconsistently and you want examples, review habits, and organizational signals that make writing part of the work.
You are building an AI-focused product and need to rethink how users learn a product whose interface is real-time or multimodal.
