Docs redesign

You had to choose from the start whether to read our concepts or follow one of our tutorials. Users eventually feel lost after struggling to decide which paths they should take on depending on the level of their knowledge of our services.

That was not helping our users project themselves into our product. We often used feature names as titles instead of guiding our users toward what the feature was used for.

We had one primary documentation and a lot of different community websites for every project that popped up the past few years at PubNub, such as our Demo libraries or our integration plugins. If you wanted to build a chat app implementation of PubNub, you had to go back and forth between two different websites that followed other guidelines.

To resolve those problems, we decided to completely change the philosophy behind our documentation, which resulted in three main choices:

We decided that pubnub.com/docs should be our unique entry point for all PubNub technical documentation. We decided to consolidate the content and migrate to Contentful. Now, in the same place, our users can go through all the steps of a PubNub implementation: publish their first message through PubNub and discover what real-time features they want in their app. More than just providing a better flow, this integration of the front and back end helps with the quality of the content now that they share the same architectural and writing structure.  

Instead of asking our users to choose between reading concepts or doing A-to-Z tutorials, we introduced a landing page with dynamic content (depending on if you were a first-timer or a returned user based on cookies stored in your browser) with guided navigation that walks you toward all the steps of a PubNub implementation and how to make the most of your real-time application.

Our technical documentation is not read by only one single profile but indeed many. From the decision-maker who wants to quickly evaluatePubNub’s offer to the curious who wants to know if X is possible with us, from the CTOs trying to hunt for more reliable real-time communication solutions, to developers in the process of implementation. Some are newcomers looking to have their first PubNub implementation up and running within minutes for the developers. Others are advanced users who go back and forth with the documentation to improve their current performance. And let’s not forget to mention PubNubbers themselves, who internally rely on our documentation to serve our customers.

One major shift was to introduce the concept of hubs based on their use cases. No matter the profile of our users, every topic they arrive at when navigating with the sidebar should be accessible. Then, depending on who they are, they will have the ability to deep dive into our content. It could be reading some how-to’s if developers are interested in copy-and-pasting some code snippets or exploring in-depth guides when looking to master a specific subject. Our technical writers also set specific writing choices we made that serve both Technical and Non-Technical Readers.

Those three fundamental principles drove all later choices we made, whether it be the information architecture we put in place or the user experience we wanted to offer.