Last week we talked a lot about building the future of documentation — and that’s a theme we want to continue today. The engineering team at GitBook are working on a few different features that we’re excited to launch — computed content and upgraded insights among them.

But today I want to talk to you about something new called adaptive content.

Hey 👋 I’m Steven, and I’m Head of Engineering at GitBook. For the past few months I’ve been working on making an idea into a reality: docs that can use user information to adapt to that user’s needs in advanced, powerful ways.

Why is adaptive content important?

What we’re talking about today will be a big part of GitBook going forward, as we continue building the future of docs.

Documentation can no longer be static websites that show the same information to every user in the same way. Docs need to offer a more bespoke, tailored experience to each user. And they need to work as more than just onboarding or troubleshooting destination — documentation should be more malleable as a marketing tool, too.

We also know that many docs team don’t measure the success or track any metrics for their docs whatsoever. And it’s easy to see why! It’s hard to know how docs are performing without tying them to product or business outcomes. By offering deeper, more integrated analytics, not only can you prove the value of your docs — you can see areas for improvement.

Adaptive content can help you overcome these challenges.

What is adaptive content?

Adaptive content is a new feature we’ve created to describe bringing user data into content.

At its core, it’s the concept of knowing something about a user, and changing the content of your docs based on that knowledge.

For example, if you know that a user is an enterprise customer, when landing on your docs they might see a landing page designed for enterprise customers, with specific information about features they can use.

Or let’s say you have a complex suite of products and a user has access to a specific selection of them. With adaptive content you can make sure they only see docs for the products they have access to — with the others all hidden from them to avoid confusion.

A bespoke docs experience, powered by your data

When it comes to building the logic behind the adaptive content experience, you’ll be able to handle it all through a dedicated area within GitBook.

GitBook will use ‘claims’, which are essentially per-user properties that can come from all kinds of places. They might come from your custom backend. They can come from visitor authentication, if you use that in your docs. They can even be pulled from feature flags in Bucket or LaunchDarkly.

Note: UI is still a work-in-progress and is not final

But you won’t only be able to pull information in from your product or other services. GitBook can log some visitor information automatically using cookies and other data — for example, we can see their location (from their IP address), operating system, browser and more.

These claims are data points such as enterprise=true, feature_sso=false or location=france that tell GitBook information about your customers or docs visitors.

And when you come to build your docs site, you’ll be able to use these claims to decide exactly how your content should look for each user segment.

Make your docs adaptive

Once you’ve got claims set up in GitBook, you can use them in a bunch of different ways.

Let’s say you’re rolling out a new alpha feature in your product, and your alpha testers need docs — but you don’t want anyone else to read them. Well, if you bring that feature flag into GitBook as a claim, you can show the page only to the alpha testers, and hide it from everyone else

This is just one simple example of what adaptive content can do, but there are many more.

We plan to offer three ways that you can direct your users to adaptive versions of your docs.

• Authenticated docs – prompt a user to sign in to access only the docs that apply to them

• Docs experiences – create a specific URL string — similar to a UTM — that you can share with customers or leads to offer a custom landing page or content flow

• Product-linked docs – link your product’s feature flags to your adaptive docs so that beta testers can only see the documentation for the feature flags they have access to

For our initial launch, we’ll support the first two of these options, with product-linked docs coming later.

The real power of adaptive docs

There will be all kinds of ways to use adaptive docs to help your product — from support to growth.

With data pulled directly from your product, you can serve your users faster and more helpfully when they need product information. When they land on your docs, they’ll see relevant information about the features they have access to, practical guides for a process they’re in the middle of completing, or suggestions for features they haven’t set up yet.

But beyond that, you can use adaptive docs to create custom docs experiences for different segments. Maybe your marketing team want to run a campaign focused on your API? With adaptive docs, you could create a dedicated landing page for that campaign, assign it a specific URL string, and share it. Without needing to build a new, dedicated docs site, you’ve got a custom docs experience aimed at potential customers.

Note: UI is still a work-in-progress and is not final

And down the line, we’ll link adaptive docs to our built-in insights to give you a comprehensive view of how your docs are performing at a deep, integrated level.

Did the people who viewed those suggested guides successfully complete the process they were stuck on? How many new users land on your docs, then go to your product and convert? This kind of data will soon be much easier to measure — so you can track success, but also see areas of your docs that could be improved.

When can you use adaptive docs?

As you can see, we have a lot of big ideas about what adaptive docs will do.

To start with, we’ll be launching adaptive content with support for individual pages and site sections — so you can show or hide those to customers based on your claims.

And as mentioned, our initial launch will include adaptive docs that require a login, and adaptive docs that use specific URL strings that you can define.

We’re still working on the final details, tweaking the UI, and fixing bugs — but we’re close to launch and we’re super excited for you to get your hands on it.

We’ll have more to share in the coming weeks. And if you want to be among the first people to test out adaptive content, you can join our waitlist. We’ll reach out soon to a small number of teams to help us finalize the feature and get it ready for general release.

→ Join the adaptive docs waitlist

→ Upgrading insights: how and why we’re improving docs analytics

→ Computed content: What is it and how is it helping us shape the future of docs?