Leveraging Integrated Documentation
We, at Hevo, are obsessed with the enriching experience we want to provide to our customers. This means reducing the efforts needed to be put in by the user and facing minimum challenges while configuring a Pipeline. With this goal in mind, we started analyzing the reasons for failures during a pipeline creation and the data indicated that the customers churn mostly at the source configuration step due to the connection failures.
This led to the idea of introducing Side-By-Side (SBS) documentation which is integrated right into the source configuration page. With the help of this documentation, the user can follow along with the required credentials necessary to configure the desired source correctly without any failures. This, in turn, will lead to an improved customer experience.
Implementation
The first challenge was to reuse the content which was already available as this type of information was already maintained and updated regularly in our documentation. So, we had to devise a method by which we could have 2 separate builds that make use of the same content. Our documentation makes use of Jekyll to generate static web pages which are then served to the user when visiting a page.
Jekyll allows multiple builds which can make use of the same content bypassing different configurations in the form of a YAML file. In the configuration, you can specify the layout that you wish to use, the source directory where the content is provided, the destination directory where you want the HTML files to be placed after the build, the plugins to use, etc. The list can go on and on. To know more about the various configuration options that are available in Jekyll, you can refer to it here.
This is the approach that we decided to take here. We ripped apart the layout of the original documentation to remove the header, footer, and sidebar and kept the bare minimum which was really essential for the SBS documentation. This was done with a view that the focus of the customer should lie on the content and not anywhere else. Now, the layout was ready for our SBS documentation. But, there was another challenge that needed to be taken care of.
Navigating the Challenges
Our dashboard supports two modes — light and dark. We wanted to achieve the same for the SBS documentation as well. When the mode is changed from light to dark or vice-versa, the change should reflect on the documentation that we have integrated. So, to handle this correctly, we made use of CSS variables. We defined theme-based variables, having the same name, and the value these variables pick will depend on the mode the user is in currently.
Now, Jekyll provides built-in support for Sass, and using Sass for styling makes the life of a frontend developer really easy. Sass brings with it the really awesome @mixin and @include functionality. Coming back to the CSS variables, these variables, then, pass their value to Sass variables and we made use of these Sass variables throughout the new layout we created. This solved the problem surrounding the theme handling in the SBS documentation.
Coming to the implementation details on our dashboard side, we employed an iframe to integrate the documentation into the source configuration step. Iframes are frequently used to embed another web page into the current one. This made things easy for the dashboard since the HTML page is ready to be loaded and it is not dependent on the dashboard anyhow. This reduces the coupling between the two.
Communication Between the Two
Now, a major concern that needs to be addressed here is how the two will communicate with each other. This is necessary to communicate when the color mode changes in the dashboard and the SBS documentation updates its color mode based on that change. For this, we made use of the postMessage API which is provided under the Web APIs and exposed by the Window object. Now, we had event listeners within the dashboard which would get triggered when the color mode (theme) changes and makes a postMessage call to the iframe containing the HTML for the documentation. On the documentation side, we had a listener for the dispatched message event which would listen for postMessage calls made to this window object and take appropriate actions.
The postMessage API can also be used the other way round. We can make postMessage calls within the SBS documentation to emit messages to the parent window which is the dashboard here and add the dispatched message event listener on the dashboard to listen to such events. This way we can make it a two-way communication even though it is not supported by this API. This helped us to keep track of certain events taking place inside the SBS documentation and pass on the information related to such events to the dashboard for analytics purposes.
Outcome
All the efforts put in by us to make this feature as useful as possible led to an upbeat outcome. This is what the end result looks like:
The world of data is changing and is never going to be the same, if you think it is worth being a part of our mission and work on challenges like this, give us a buzz at 100guns@hevodata.com.
