Top-tier documentation stands out immediately—it’s thoughtful, comprehensive, and easy to navigate.

But the process of creating this kind of sleek documentation is far from easy. Behind every swoon-worthy documentation asset, you can bet there’s a technical writer or developer who swooned while writing it. And not in a good way.

Although documentation is often created for (and by) tech folks, writing docs that hit the mark requires more than technical knowledge. You also need an understanding of the holistic product, and of the needs, challenges, and goals of the developers who use it. And we’re not afraid to say it—you need to be both a strategist and an artist, a right-brain and a left-brain person.

To help you create documentation that both inspires and informs, we spoke with experts in the field to uncover the recipe for best-in-class documentation:

• Rachel Nabors, a fractional developer experience leader, previously at Meta, AWS, and Clerk.com;
• Casey Smith, lead technical writer at Payabli, previously at Amplitude and Salesforce;
• Amruta Ranade, previously technical writer at Cockroach Labs, Airbyte, and Druva.

Here’s what they had to say.

The write stuff: Understand your audience

The first step, before you lay down the first word, is to develop a deep understanding of your audience. That means knowing not only who they are, but also their common experiences, challenges, and basic information like their preferred programming or coding languages.

If you’re new to documentation or have limited experience with developers, take the time to learn about how they work and the ecosystem around their roles. As Casey notes, the key is to avoid assumptions about your readers and stakeholders. Once you understand your audience, here are tips to help you write the docs it needs:

Provide context

“You have to realize that the audience is not you,” Rachel says. “They don’t have the context that you have.”

So, it’s up to writers and documentation managers to elaborate and fill in the gaps. Picture yourself in the shoes of someone who just found out about your product. What do you know that they don’t?

Define the outcomes

Make sure the end goal is as clear to your readers as it is to you. Define what you want them to learn or accomplish, and then make sure that everything you write supports that outcome. To guide readers through the content, Rachel recommends starting with the five W’s: who, what, why, where, when—and of course, how!

Become an expert on the product

The better you understand the product, the better you'll write about it. Amruta suggests thorough testing as if you’re the first user and consulting product experts for edits, reviews, and feedback.

Smart navigation: Create strategic paths to information

Great documentation isn’t just about the right words—it’s also about helping readers find the information they need easily.

Stellar navigation combines thoughtful information architecture optimized for internal and external search with content tailored to the audience’s specific problems, backgrounds, or touchpoints along their user journey.

Traditional documentation navigation often focuses on information architecture at the page level and resembles a table of contents. Content is goal-driven, well-structured, and based on a precise understanding of users' mental models. This page-level architecture takes into account when users "pogo" in and out of content, searching for the right answers rather than reading in chronological order.

But in reality, most users access information by going straight to external search engines like Google. "Navigation may be great for browsing, but not necessarily for solving problems," says Casey.

In such cases, Rachel says, it’s important to boost the SEO of your documentation’s content to help pages rank higher in search engine results. Equally important is optimizing for internal and AI-assisted search.

A good middle ground between traditional and search-centered approaches, Casey says, is developing navigation that provides both narrative context and content for specific user journeys. By creating tailored pages for each user touchpoint in the product, navigation can provide a useful, highly personalized solution for the audience.

Consider a step-by-step guided approach to documentation. This model gamifies the navigation process and unlocks new levels of knowledge in increasing degrees of complexity as readers progress, says Amruta. The first stage is the “getting started” page with a glossary, references, and key components. The second stage contains how-to guides and introduces core concepts. The third stage includes use cases and examples.

Breaking up content by audience is also a great way to design personalized docs pages.

“Right now, documentation puts out all levels of information and asks readers to figure out what they need by themselves,” Amruta says. “In the future, we can aim to serve the right content to the exact audience profiles that need them.”

Don’t Repeat Yourself (DRY)

“Don’t repeat yourself” is a powerful code-based concept for optimizing documentation.

Techniques for reducing repeated content include transclusion or nutshell patterns. Transclusion modularizes content, while nutshell patterns provide information just in time, enhancing the reader’s experience without disrupting their flow.

Snippets help reduce repetition by maintaining consistency across multiple parts of your docs. According to Amruta, snippets provide a single source of truth, accommodate various reader entry points, and eliminate the hassle of updating multiple references at once.

At Payabli and Amplitude, Casey used a meticulous system of naming conventions based on feature areas to boost efficiency in her docs writing process. As a best practice, she recommends organizing snippet directories and naming conventions clearly from the start to save time later.

On the flip side, as Rachel notes from her experience with React Native docs at Meta, there are times when repetition is helpful. Docs that mirror what readers see in source code help them trust that information is current.

Docs as code: By developers, for developers

Writing for developers means using the same tools and workflows they use.

For both Casey and Rachel, treating docs as code creates a more inclusive writing process. This approach allows developers—who are both expert contributors and users—to easily share their technical knowledge, making it simpler for documentation writers to build on.

It also helps overcome potential language barriers for those who may not speak English as their first language. Also, if developers do not fully appreciate the importance of documentation or view it as a chore, treating docs as code fosters a documentation-focused culture by integrating the writing process into their existing workflow.

Understanding that product developers are also product users is one of our core design principles here at Mintlify. You can read more about how our team designs for developers here.

Updates and changes: Docs as a team effort

Updating docs should be a team effort. It’s all about making it easy to edit, gather feedback, and get everyone’s input and approval. Keeping the update process open and straightforward, plus having a quick review turnaround, is key.

From Rachel's experience at Meta and AWS, clear metrics help guide the overall docs strategy. They help identify specific issues and areas that could benefit from more optimization across pages. Important metrics include:

• Average age of docs (ideally as recent as possible),
• Average reader rating for each page and the documentation overall (preferably above a 75% thumbs-up rate)
• Page traffic

Intersections of these metrics can help you detect “hot spots.” For example:

• High-traffic, low-ranking pages need emergency intervention
• Low-traffic, older pages should be updated for relevance
• Older, high-ranking pages with little traffic should have their SEO and discoverability reviewed
• Low-traffic, high-ranking pages can have their content or framework replicated across other parts of the documentation to increase visibility

To stay on top of content issues, seek feedback from customer support, engineers, and even open-source users, says Amruta. Staying closely connected with the engineering and product teams is also important, as they can help identify issues too.

Amruta suggests these techniques to streamline docs updates:

• Check links: Broken links are tough to fix later on.
• Preview changes: Writers can see how everything will look and review the content and flow before finalizing.
• Snippets in VS code: This lets plug-ins and integrations handle repetitive tasks.

Overall, a strong review process that works well for both technical and non-technical folks can save docs writers a lot of time and hassle later on, says Casey.

Final tips from the pros

At the end of the day, there are countless methods for creating great documentation that developers actually want to read. Our experts agree that good documentation comes down to the quality and personalization of content.

For Rachel, this means having docs managers who can effectively communicate with engineering teams and manage KPIs and metrics, alongside engineers who actively collaborate with the docs team. Only then, she says, will quality information from engineers be built into docs processes and directly address customer concerns.

For Amruta, this means understanding that “the more the tools develop, the more technical writers need to focus on the fundamentals.” Newer and more powerful tools free up docs writers’ time to focus on the essentials—be it the audience, the content, or the context.

For Casey, it’s recognizing that some users don’t pay close attention to the docs. “There’s always going to be a developer who doesn’t read the content and just runs the code sample,” she says.

No matter how well-crafted your documentation is, there will always be people who skim. That’s something you can’t control. What you can control is creating the best possible docs for the developers who take the time to dive in.

Your turn: What makes the best docs for developers?

Writing documentation is complicated, especially when you need to account for multiple product lines, audiences, and ways to build. In our conversations with Rachel, Casey, and Amruta alone, we uncovered a wide range of strategies for creating great docs, spanning from navigation, to audience context, to docs as code.

Learning more about what goes into stellar documentation is a constant journey for us. Have any fresh perspectives or topics about writing developer-friendly documentation? Share them with us on X!