When creating a resource and community to help developers get the most out of your product, it’s important to empower them to contribute to developer documentation and not just have all your content coming from product or tech writers.
If you haven’t read how we overhauled our developer portal recently, check out our prior conversation with Moti Granovsky, Sisense’s Head of Developer Relations. In this second part, we will take a deeper dive and share how we built a new system from the ground up to both deliver great information and be flexible enough to allow for continued evolution and growth.
Let’s kick off our journey into the rebuild by understanding what our requirements were and how we went about meeting them.
Jack Cieslak: Why did we choose to build the portal on our own from scratch and not just use one of the many great products out there?
Moti Granovsky: There are great products out there focused on developer documentation, which are used by many companies successfully. When we set about rebuilding the portal, we knew we wanted engineers to contribute to our developer documentation. We also wanted to auto-generate some of the content, especially API references (which are very dry; there’s no “writing” necessary). Our product has so many APIs (rich and large) that writing and maintaining them is very time-consuming. We didn’t want tech writers to waste time repeatedly updating tables and tables of parameters.
We wanted to invest our time in generating content that is more engaging and valuable, like tutorials, open-source demos, cool features, and so on.
JC: What were you asked to do?
MG: Our requirements were, in essence:
We looked at products in the market, and none of them met all of these requirements combined. Additionally, they were relatively costly because they include hosting, but documentation is generally static content so it is cheap and easy to host. There was no reason we couldn’t build it ourselves since we have the technical know-how to do it in-house.
JC: So what tools did you decide to use to build the new portal?
We found one called VuePress that did exactly what we needed. It has all the flexibility in the world. It is an open-source framework built and used by the Vue.js project. It allowed us to build exactly the type of website we had in mind in terms of look and feel while avoiding a lot of the effort involved compared to starting from scratch.
We invested effort in creating a great design and refactoring a lot of the existing content we had into Markdown from the old format. However, this process let us build the new portal from the ground up exactly the way we want without any compromises.
While it took a lot of effort initially, in the long term it will all pay off. First, the hosting is very cheap. Second, if we have to add new content, we don’t have to design anything. It will only be as expensive as writing that text. Anyone can just write text in a notepad and have beautiful content up on the website.
JC: What can users expect to find in the new portal that they couldn’t in the old one?
MG: As a result of the new design, there are a few big changes in the new Sisense developer portal:
Overall, the content now is not just a block of text but part of an ecosystem of knowledge that developers can utilize. Everyone has a different learning process. Some prefer to read, some prefer to see a demo, some like to watch a video while others prefer to just dive right in and learn through experimentation. We are trying to provide different ways to help no matter what a person’s approach to learning is.
In addition, we also have features that cover:
In the future, we are looking at adding a developer-focused blog within the portal directly. We are also continuously working on more video content and documentation for some of the APIs that aren’t covered yet.
JC: Lastly, how can an organization decide if building its own developer documentation site ground up is the right approach for them?
MG: Take into consideration these points to decide if this approach is good for you:
It all boils down to capacity and need. If your current documentation website works and customers are happy with it, and all you need to do is to enhance and update the content, then do that. Don’t waste your time and money on building something new. But if you have a lot of room for improvement like we did, and you want to use the opportunity to upgrade and overhaul the user experience, then this is a viable solution that should be considered.
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.