Always Accurate Documentation

Over the years as a designer and engineer, I've written documentation for many different projects, sometimes in a rush and sometimes with a team over many months. One constant across every surface is that it doesn't take long before you or your teammates start finding outdated explanations and code examples. I'm Travis Arnold, and throughout my career, I've seen how outdated documentation can cause friction and work flows and erode trust in projects. It's a challenge that engineering teams of all sizes face, and in this talk I'll explain why documentation drifts, how to catch it early, and how React server components can help keep your documentation accurate as code changes.

We'll cover three main topics. Why documentation drifts, using React server components to keep documentation in sync, and finally how to write accurate documentation everywhere. Let's start with something we all know too well. A code example. We've all copied code snippets that are provided as a source of truth only to hit TypeScript errors later when pasting them into our code base. Imagine a developer is excited to implement a feature, but they're halted by unexpected errors in outdated documentation. This is documentation drift, and it wastes hours of time.

It's happening for a few reasons. First is that while traditional documentation generators work well for simple docs, they have several limitations. They produce a fully baked HTML site that is hard to customize. They expose JSON that requires extra integration work. They often require their own build process. And they cannot granularly update generated types which creates performance bottlenecks. And if you want to customize or overwrite the output or connect it to your design system, you end up creating workarounds and orchestrating multiple tools that all have to be kept in sync. One of the most common reasons documentation drifts is the lack of a single authoritative source for what's actually true. Instead, information is scattered all over the place. Source code lives in a repository, API specs are in a separate documentation site, and usage examples are pasted into marketing materials. Each of these sources evolves independently and often out of sync.

This fragmentation means there's no guarantee which artifact is the real reference. As teams update code, documentation and specifications in parallel, contradictions will inevitably appear. To solve this, documentation needs to be tightly coupled to the source code itself. When docs are generated and validated against the actual code base, you eliminate any ambiguity. Docs drift not only because they're not connected to a single source of truth, but also because they're spread across a large number of places.

Docs exist across read me's, sites, blogs, slides, and marketing materials. There's different teams maintaining those services which can cause drift. And copying and pasting propagates and last minute changes will often get missed. A code snippet might begin in a developer's IDE, get copied into the read me, and later appear as a screenshot in marketing. When the code changes, these copies often stay outdated. It's similar to a game of telephone where truth can easily break down.

Docs will go stale if they're not tied to a source of truth. For example, at a startup I worked at, we didn't have a dedicated documentation team, and engineers and designers helped out when they could. But because of this, our documentation tools had to fit right into our normal workflow or they just simply wouldn't get used. Building these systems yourself is rarely practical. You need deep knowledge of abstract syntax trees, otherwise known as ASTs, which represent your code's structure, plus tooling to traverse and transform them. For languages like TypeScript, you also need to understand the TypeScript compiler API and the type checker.

With the introduction of React server components, we gained a crucial ability to render components on the server. This pairs extremely well with tooling such as TypeScript. By generating documentation straight from components using the TypeScript compiler, you avoid copying outdated code snippets. Instead, you show information directly from your codebase so your examples and docs stay in sync with every change.

React server components solve several key problems that make them a great fit for documentation. First, we have server side execution, which allows safe access to TypeScript project files and other metadata. Moving heavy lifting to the server enables parsing and typing types and formatting code efficiently. Composition now offers flexible rendering of components across various platforms like readmes, doc sites, and marketing materials. Streaming, a significant feature, enables a great documentation experience both in production and locally.

Leveraging React server components allows for lazy evaluation, deferring work until necessary for optimal performance. Examples of code blocks and reference components from a library demonstrate the advantages. By rendering directly from source code, syncing with updates is ensured, enhancing flexibility and accuracy. Direct consultation with the TypeScript compiler ensures the most precise API references for teams, including type signatures, props, generics, and default values.

Finally, we have lazy evaluation. The best performance is to do nothing at all. React server components allow us to defer work until absolutely necessary. Documentation sites have many moving parts, so this works out really nice.

Let's look at some practical examples of how React server components can help bring the TypeScript compiler into the loop. We will use two components from the renowned library to illustrate what React server components provide to documentation. First, we have the code block component, which renders from source files or virtual examples, which will be validated against the tsconfig.json file in the project, as we saw in the beginning of this talk.

By moving these concerns to the server, we gain a lot more flexibility and control over the content we render while still ensuring it's accurate and up to date. So if we use these examples directly from source code, they will always be in sync inherently, which is really nice. Code examples are great, but teams also need API references like type signatures, props, generics, and what default values are available. This is where the reference component comes in.

While we're using inline text here that might have come from an external source, as we can see in the template literal text here, we can also render code blocks directly from the source files on disk. By moving these concerns to the server, we gain a lot more flexibility and control over the content we render while still ensuring it's accurate and up to date. So if we use these examples directly from source code, they will always be in sync inherently, which is really nice. Code examples are great, but teams also need API references like type signatures, props, generics, and what default values are available. This is where the reference component comes in.

This component consults the TypeScript compiler directly, so you always get the most accurate API references. The key difference here from traditional documentation tools is that we can lazily ask the compiler for this information only when it's actually needed, rather than pre-rendering it all in a separate build step and having to wire it up manually. We can even granularly filter the information we want, so we only include what is relevant to the current context. This is really nice as well, since we can tie it exactly to the source code.

Similar to what we've always done with React, we can now mix and match and combine these components together to create a more complete documentation experience. This gives us a lot of flexibility to create a documentation experience that is tailored to our needs and does not sacrifice accuracy or maintainability. React is used on every platform, from web to native apps and even virtual reality. With React server components, you can now get the same experience of learn once, write anywhere, and deliver accurate documentation wherever your product goes.