How to Build a Flexible Developer Documentation Portal

[moti]

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.

Building instead of buying

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.

Make your requirements specific 

JC: What were you asked to do?

MG: Our requirements were, in essence:

1. The platform should allow us to separate styling from content. We wanted to make sure that unlike the old website, it looks great, matches the Sisense brand, and keeps on looking great even as more content is added. This means not only did we want to white-label and design the content, we wanted to separate the layout and design from the content. (Remember, the people who are writing documentation are not necessarily experts at visual design.)
2. The format should be accessible to developers (aka Markdown-based). Besides an UI-based editor, some content management systems have their own specific language to programmatically format content. However, oftentimes nobody knows enough about these languages, and they’re not very intuitive either. Instead, we looked at the most common way for developers to write content — Markdown. It is used by Git itself and all Git providers. Even readme files for projects are written in Markdown. Every developer knows this syntax, and it has this benefit of separating design from content. Markdown content will also allow us to auto-generate content. If you look around, most API tools like Swagger, for example, have the ability to generate Markdown content.
3. Our customers should be able to contribute to docs (eventually). If a customer finds a typo or a mistake or they want to add some detail, we want to make that possible. For that, we should be able to store the content somewhere public, such as a GitHub repository. Markdown makes this possible since it’s text format and can be easily shared in GitHub. But we need the content to be separate from the website itself (something that is publicly available). If we were to write HTML pages and put them on a server, then a customer can’t contribute to that. But if those pages are generated from something that is publicly accessible like a GitHub repository, then we can solve this challenge.
4. We should go beyond just the documentation. We wanted the new website to be a true developer portal — a hub of knowledge and information for developers with which they can find all the resources they need. We want to make sure that, in the future, it includes a blog, playground, links to community, etc. that are not necessarily documentation. We want to create a home for developers where they can come and find anything that they need to do their job.

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.

Choose the right framework

JC: So what tools did you decide to use to build the new portal?

MG: We found out some companies (and a huge shoutout to the developer relations team at Okta whose approach to developer docs inspired us) have taken this different approach and built their own websites using different tools. There are frameworks that can generate websites from Markdown. We looked at different ones and picked one that fit the Sisense technology stack (in terms of languages that developers are familiar with. Since most of our developers are JavaScript developers, we wanted one that used that and not Python, for example).

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.

New portal, new options

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:

• Separation of API reference and documentation: Developers can find a dedicated API reference section that is well organized and structured. They can quickly access the exact information they need. It is a lot more detailed and a lot more standardized than what we previously had, and they don’t have to scroll a bunch of text to access what they need. 
• More code samples right within the documentation: Code can be easily copied with a copy code button. It is nicely formatted, and the syntax is highlighted according to the language, making it much easier to read.

• A lot more cross-referencing and links than we used to have: When something is mentioned, it is always linked right there, or you can find the relevant link at the bottom of your page. You can navigate through and gain all the knowledge to accomplish a task without breaks in the thought process.
• Improved search: You can quickly see search pages and headers within pages. You can quickly jump into specific areas within a page.

•  Responsive mobile experience: We also optimized all pages for mobile consumption.

• New and refactored content: Much of what’s been added to the portal is entirely new, plus we refactored a lot of existing content, revalidating and updating it.
• Broad range of content types: We added a lot of external references to our GitHub account, webinars hosted on Vimeo, and a playground built in conjunction with the 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:

• Developer release notes and release notes for the website itself so you can track what has changed
• More about the DevX team, why we exist, and and how to get in touch with us
• Ability to reach the playground, blog, and forums from the portal directly

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.

How you can improve your own documentation

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:

• You need engineering capability to build the website. 
• You need to make sure that the people who are writing documentation are comfortable with the format. For example, if the people writing documentation in your organization are technical writers who are comfortable with Markdown, then great, use this approach. Or maybe they want to learn, then that is great as well. If they do not want to learn, they may need another platform that is what-you-see-is-what-you-get.
• Make sure you have the ability in terms of IT to host and maintain the site. If you can’t assure that it will be up globally and available 24/7, then you are going to have problems. Since this is the largest interface with the largest surface area, fault or downtime will have a huge negative impact. 

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.