Personalization of the developer experience

Personalizing the developer experience is one way we’re making our product more accessible. Here’s how we did it.

We’re excited to share the latest updates on the documentation experience from VGS. One of the key components we’ve introduced is a new and reimagined personalized developer user experience.

What is personalization and what is the purpose?

Personalization of UX can be described as changing the UI by showing specific data or content, part of the product, or a certain product behaviour to meet a customer's individual requirements.

The personalization of the documentation portal is intended to provide a seamless experience for you, with personalized content that::

• Is easy-to-grasp.
• Is relevant to the user's needs.
• Leads you from the beginning to a successful result.
• Is responsible. We’re constantly thinking about which problems the user can face and use cases our user is trying to solve.

How did we do it?

There are different types of users that land on VGS docs; some users want to troubleshoot their integration, others want to know more about solutions VGS provides so they can better meet their business objectives.

This is what makes personalization of the user experience so challenging. It’s a continuous and iterative process. It requires a complex approach and it’s important to use best practices described in known books. But it also contains some nuances that we at VGS think are valuable to our customers.

Personalization should be varied and consistent at the same time. We should speak to our users in a variety of ways and help on each learning step, but in a predictable and easy-to-understand fashion.

To do this, we’ve defined several fields as important to personalize: code examples, text content and visual content. Let’s explore each of them.

Code examples

As a technology company, we have a lot of code examples. Some configuration is required and we offer solutions in many programming languages. Like many other developers, we use GitHub as a central repository for VGS code. As many of our customers are also developers, it feels more natural to give access to code examples on GitHub.

Tooltips, link to visit on GitHub

The majority of our code snippets content is accessible on GitHub. The only drawback for GitHub snippets usage is that you can only leave some static comments in the code. So to provide a personalized experience, we combined an approach of a tight integration with GitHub, with dynamic tooltips that are working as an additional layer over the code. We read the content from GitHub and process personalization over it at runtime. So, the user, while loading the documentation samples, gets own description for everything described in the code.

Working code

But that wasn’t enough. We decided that the code itself should be personalized. This helps to copy paste your code right to the terminal. Our next step was to change code examples and show them individually, even with auth based content. To do this, information is taken from the user's existing session.

If the user cannot be authenticated we just show test credentials for the public accessible sandbox.

Interactive code

Another challenging step we started working on is an interactive code. Why should users go outside of documentation and run the code in the terminal if it’s possible to run code directly on the page where you can see it for the first time? This is the most complicated part and typically, needs quite a big footprint. And, of course, there are a lot of ways to make smart and affordable solutions (pre building code execution results, hardcoding, delegating code execution to the third party services, etc).

Check out our “Try it out” button at the right top corner of code snippets.

Texts

Personal guides should bring a unified and personalized experience to everyone. After all, why should users see non-relevant content while going through the introduction guide? Users deserve to see the matters the most to them, and answers their questions.

Relevant content

Relevant content topics should be close to each other to make the experience more convenient for the user. For successful personalization, you need to be aware of what is related to the current article and what value that suggested content would provide.

User progress

It’s valuable to the user to see the progress on passing onboarding guides or reading documentation. Everything should be measurable—even time that the user spends before the initial setup is completed. This not only gives them a feeling of completion but helps them understand the time investment required.

Warning and notification bars

Everything in your documentation should be in the right place at the right time. In addition to content restructuring, we should think about our users and try to prevent common mistakes.

For example, in the case text documentation, we should point out that some configuration is sensitive and potentially would lead to misconfiguration. In terms of personalization, we can analyze current user configuration and tell the user that something is misconfigured even before they run any code. And, of course, these notifications can lead to the correct troubleshooting.

Visual content

Demo videos

It’s not a secret; users like videos. It’s easier to understand something when you can see it. With the help of video tutorials, we can reduce the text amount and increase our understanding. When the user behaves exactly as demonstrated in the video and receives another result, that’s the marker that we should change something. The video content could be a referral point of truth for the user. Here is an example of how we integrated video tutorials into our docs.

Interactive playgrounds

It’s important for users to be able to learn something without touching the code. The guides we’re using help users better understand the setup order and avoid misconfiguration. After the guides are finished, the user has already some basic configuration. An example of a playground for a basic understanding of integration with VGS can be found in this interactive guide.

Screenshots, charts

Visual content can also clearly highlight device interconnection and other complex concepts. It’s hard to explain what the aliasing means, but when a user can see a simple flow chart, this becomes super easy and intuitive. For example:

This is an additional way of creating a seamless user experience without the risk of overwhelming them with documentation.

Personalize code snippets from GitHub.

It’s super convenient to store code snippets at GitHub. We’re using a dedicated repository that’s connected to our documentation out of the box. And while it’s also possible to connect other repositories, that’s a story for another article.

Our implementation only requires you to pass the name to the corresponding file from the repo and all other things will be done under the hood.

Personalize inline code snippets.

What we’re doing is not limited by GitHub content. It’s possible to personalize code snippets directly hardcoded by page content. It’s possible not only to change placeholder values, but also add personalized tooltips.

For developers by developers. Personalization Interface

The personalization should be configurable as much as possible. Configuration should be simple, so every developer in a company can apply it easily. That’s why we use a declarative approach here.

We understand that data manipulation on the frontend can be quite tricky. That’s why we’ve added personalization as a frontend abstraction layer that has access to some pre-determined personalization data, such as information related to the current organization, its current vault, and other static data.

All this together provides an interface to work with personalization via configuration objects. Developers just need to provide a map of values for personalization, the format of placeholder and a number of pages where need to apply such personalization.

Conclusion

Implementation of personalization to our customer-facing products brings a valuable commitment to the entire user experience. It’s not something a user can’t live without but saves time for both the user and our team on investigating and solving problems. After all, the days are long gone when a company-focused product or design was “good enough.” With putting the user experience first, we can better our product while ensuring the user has a pleasant and effortless solution.

We’re constantly working on improving the personalization approach we’re using to make integration with VGS easier and more efficient.