Building a Better Developer Documentation Portal

[moti]

The new Sisense Developer Portal doesn’t just look great, it’s also built from the ground up with developers in mind. As you explore it, you might be asking yourself, “Why did you decide to invest in the new developer portal?” “What was wrong with the old one?” “Why was it worth your time and effort?”

These are all great questions, and we have lots of answers for you. To get them, I sat down with Moti Granovsky, Sisense’s Head of Developer Relations (and API architect), to delve into the reasoning behind the redesign and the ways the improvements will make life better for developers looking to incorporate Sisense into their products.

We talked a lot and in this part of the conversation, we look at why it’s important to take a pure developer-centric approach when building your documentation portal.

Maximizing the largest interface with developers

Jack Cieslak: Why was it important to overhaul the Sisense Developer Portal?

Moti Granovsky: The developer documentation is the interface with the largest surface area where we as an organization interact with developers. Beyond anything else we can do — events, webinars, blog posts, and anything else outside the product itself — the documentation is the place where we have the most interaction.

Any company that sees developers as an important audience needs to invest a lot of effort and thought into this endeavor. It’s obvious that many different developers at different stages (pre- or post-sale) who work with Sisense will end up in the documentation pages. It’s a given, and this is something that we have to keep investing in.

Better content means a better developer experience

JC: In what specific ways does such an investment help? 

MG: Investing in both developer content and the website itself (how accessible it is, how intuitive it is, how easy it is to read, etc.) pays off in the long run, both from an improved customer experience perspective as well as cost savings.

Generating any piece of documentation is a one-time investment per topic, but it can help many people for years to come. Users can just look at static content and gain the knowledge they need, decreasing the load on support teams, solutions engineers, or pre-sales engineers.

Building a portal where the right content is easily accessible helps reduce the number of questions from developers dealing with your product. This is because developers will almost always first seek a written piece of content before they seek direct interaction when they have a problem they are trying to solve.

More documentation also delivers a better customer experience, because even if a developer does have to ask a question, there is a good chance that the internal employee who’s tasked with answering it can direct the customer to a written resource that has been validated and has been written in a language that is understandable for everyone.

Ultimately, better content, easily accessed, leads to a better customer experience.

Good documentation is an indicator of a mature API ecosystem

JC: APIs are an important tool in a developer’s toolkit. How does documentation play into the world of APIs?

MG: If an organization’s APIs are a mess and no one knows how they work, then it is really hard to document them. The reverse of this is, if someone is going to buy a product and they don’t see good documentation or see partial information, then this tells them that the APIs are not good.

Sisense has good APIs. We are proud of them and we want people to use them. But more than that, to convey the idea of the strength of our APIs, we need good documentation. Transparency, standards, and consistency are immediately visible in the API documentation. If one cannot see these qualities, then the API itself is likely to be more difficult to use.

Developer documentation should be built for contribution by developers

JC: How is a developer portal different from the rest of our content?

MG: Specifically, in our case, our website was outdated: We used a content management system (CMS), which is very common in tech companies. However, our CMS was chosen because it was accessible to the type of people who wrote documentation initially, mostly product managers and technical writers who are not developers and prefer a what-you-see-is-what-you-get (WYSIWYG) user interface (UI)-based editor. They would write content the way they would for white papers, blogs, etc. For this need, a white-labeled content management system with some aesthetic tweaks did the job. Also, a white-labeled CMS was quick to put together and easy at a small scale.

For developers, a WYSIWYG editor is not necessarily the best approach.

Since we are talking about developer documentation, the majority of the content should be generated by the developers building the APIs and not by technical writers or product managers.

Developer content does not really lend itself to article-style publication.

There are specific layouts that are very common across the domain of technical documentation, especially when we are talking about API references. APIs are repetitive. Manually going in and writing that — taking a bunch of headers and making them a certain size and color in a what-you-see-is-what-you-get editor — is time-consuming and prone to errors.

Say an API has 60 functions and one has to manually edit the style for 60 headers; this process cannot scale. Also, in a CMS, you can’t easily auto-generate content because typically everything is UI-based (or has a proprietary language/syntax for a programmatic approach).

Developer documentation is multi-node, not hierarchical.

The original site was built by technical writers who were focused on product documentation where you look at documentation as one bulk of information, a hierarchy of articles. Developer documentation is different: It’s not hierarchical; it’s multi-node. You can’t put all the information on one page. 

For example, API references always need to be separated from written tutorials. As a developer learning an API, I want to read the tutorial that walks me through using it, but as someone who knows the API and is using the API for development, I want one place where I can go look up a function I am interested in and look up the relevant parameters. I also don’t want to scroll through pages of content to find one function and its parameters.

Building better together

Creating a new developer portal is a key part of giving the Sisense developer community the tools they need to do more amazing things with Sisense. Everything about the new Sisense developer portal is designed to help developers of all kinds find and share content and information that will help everyone. When we build together, everybody wins. Be sure to check out part two of our interview with Moti to see how we are empowering our community.