Content as a Service for Documentation, the Best of Custom Solutions
Maintaining and improving educational materials is the most important task for Technical Writers and other similar positions. But maintaining the solution that runs the whole portal usually goes along with it. Even though it's not the key focus of Customer Education teams, the choice changes the resulting experience heavily for both your customers and your authoring team. There are 3rd party solutions and custom solutions, which have their pros and cons, but we have chosen a different approach—using a Content-as-a-Service product.
Why 3rd Party Seems to Be the Best Party (and Sometimes Is)
Typically, when you start with customer education, you want to start small. Because what's the point of investing in a huge solution when you're not sure what you'll get from it in the end? That's why most of the new kids on the block start using a 3rd party documentation solution. It's surely what we did when we started with both our products, Kentico EMS and Kentico Kontent. There are many of 3rd party solutions, better or worse for your specific use case, but the biggest advantage is that the solution just works—the only thing to do is configuring the solution in their UI, and you're live.
If that 3rd party solution still meets your needs after you've become a well-established company, don't hesitate to keep using it. If there's a vendor that creates a product exactly as you want it and you don't pay thousands of dollars every month for it, just keep it, they actually save you money.
However, if it were that simple, this blog post would end here and now. Most usually, one of these three scenarios unfolds:
- The solution was cherrypicked in a phase when you had different requirements, and now it's not that great with the current requirements or future goals.
- The cherrypicked solution starts to be developed towards a different direction than you have taken with your documentation.
- The reasonably priced cherrypicked solution increases its costs significantly as they start realizing their value.
We've experienced all those scenarios, and in any of them, you can do two things—either pay more money to persuade them to keep their product relevant to your needs or go elsewhere. Over time, when the world started realizing that a happy customer brings you more revenues than an unhappy one, the vendors of educational portals started realizing it too, so you get much better tools than ten years ago, but you pay for them much more as well.
Do you need to integrate? You need to pay for it. Do you need to know where users spend time and click? Pay again. Do you need additional tracking capabilities? Just pay. For us, one of the main reasons to leave our 3rd party documentation solutions was that we wanted to connect it not just with Google Analytics, for which most solutions have built-in connectors (some for a price), but also with other systems, like our SSO for both customers and the education team or Intercom user accounts.
3rd Party Roadblocks on the Way to Success
I'm talking all the time about requirements and directions, but what problems are there actually? I won't be preaching about something we haven't gone through ourselves. Over the 15 years of Kentico history, we've tried multiple different educational systems. We have tried an on-premise documentation publishing system, a hosted wiki-type software, a custom-built API reference generated from the source code, a developer documentation software with different modules like articles or an API reference, and a help article software paired with a customer service product. I don't want to name them as I don't think they are bad products; our and their strategy just parted ways at some point.
Each and every one of them had its benefits but also its shortcomings. Besides the mentioned integration problems, which occurred at some point with almost every system we've used, there were more common problems that usually related to the authoring experience. For example, one platform didn't have any history of changes, no versioning. Reviews were a pain. We had to duplicate content to prepare new versions and simulate preview capabilities. With a different platform, we were missing an easy way to prepare new content for releases. There was no workflow, and any saved changes were automatically published. That also meant duplicating content as a workaround for workflow. Another system didn't allow basic formatting like creating tables.
On the other hand, multiple solutions offer functionality that we had never used and didn't even intend to use in the future. That's a smaller problem but still annoying when the vendor focuses on improvements of something that you don't care about while the problems you have are still there. Also, the UI of the solution gets slowly cluttered. For example, our documentation isn't localized, so we didn't need localization buttons highlighted in the UI.
But that's our internal talk only. The most important part is that it also had a negative impact on our customers. At one point, we ended up not with one, but two different solutions. Our thinking was to split developer documentation and end-user guides—from our research, it was what users wanted. In the end, we came to the conclusion that it was an unfortunate decision. We found out the hard way, namely through negative responses, that many people can't differentiate whether they should look into this or that part of the documentation (nor do they care) and they just want their answer. Using two different 3rd party solutions came with another shortcoming—most 3rd party vendors don't allow including content from another portal in their search or replacing their search with your custom one. Customers were therefore forced into learning to differentiate between two systems and then use a search that looked only through half of the articles. They weren't often aware of the other one, so they thought we hadn't described what they were trying to find.
Besides that, if your documentation contains code samples, you probably know that maintaining hundreds of code samples is time-consuming and a nightmare if they change often. We also had the code written just as a text; it was all over the place and couldn't be maintained from one location.
After encountering all those problems, it doesn't usually take long to the revolutionary question, "What if we had something that would accommodate all our needs? Something custom..."
Custom Solutions—Good or Bad?
The obvious advantage of custom solutions is that they're completely customized for your customers and their needs. If you consider your customer's point of view, they can get experience as personalized as possible. Based on their role in the product, they can get relevant materials recommended to them right when they come to your educational portal. For example, if you know that a particular user is a marketer taking care of email campaigns, why show them the search results from your API reference? At the same time, you can extract much more information. Integrate with any service, use the same design as for your product website, analyze any traffic and customer data—those are just a few advantages that you'll get with a completely custom portal.
But with a great custom documentation portal comes great implementation and responsibility. If building documentation portals were easy, there wouldn't be businesses whose sole business model was building a portal for documentation or API references. The building of custom portals includes a great deal of planning, resources, and often project management. If you go with internal resources that usually develop your main product, you'll soon realize that they don't know your needs and they do what they learn from you. So, you will always carry the burden of knowledge on your shoulders. If you choose external resources, you'll have to design the portal right the first time or solve changes later on in the implementation. In both cases, for later cheap runtime expenses, you'll have to ensure a big budget for the development. So if there's one sure thing, it's that there's no easy way out.
Moreover, the shortcomings of 3rd-party software are usually not that the software would be bad altogether. You usually aren't satisfied with one or more parts of the software. For example, the way they version your content is insufficient to your needs, the authoring experience requires more technical knowledge than it should, or the experience your customers get is subpar. That usually delays the decision for a custom solution, often into thinking that the D-day will never come. Also, unless you present a good case to your management, the probability of obtaining a budget for such a huge project is low. Like that, I was pushing our company into going for a custom solution for over a year.
Marketing Is Your Budget
Years back, the documentation used to be a must-have but also a pointless part of every software product. Back then, you got a printed manual, later a super-long PDF, with every detail described. No one wanted to read it, and no one wanted to use it. Since that time, we have become smarter and the times have changed.
These days, in the world of Software as a Service, companies now go for loyal customers that can get higher and higher value from their product. But the customers and users usually don't know the benefits of the product themselves. Therefore, the trend is not to describe what functionality the product offers but what customers can achieve with the product. The point is not to describe every little edge case that might be interesting for 1% of the customer base but to show that the product is a pleasure to use. The documentation is no longer a boring tech talk; it's catchy educational material that will bring you more customers through word of mouth. And those aren't just assumptions—there is actual data that support this from different points of view.
For example, the Incite Group found out that 91% of B2B purchasers said that word of mouth influences their decisions. According to Powered, customers are 29 times more likely to purchase a product when they are educated than when they are targeted by traditional advertising. Forrester Research notes in their 2016 post that the usage of FAQs and other help guides rises over time. 81% of US adults use them while many of them actually prefer self-service before using support on the phone. The Technology Services Industry Association found out in their 2017 survey, which included 2,800 respondents, that 68% of users work more with a product if they're trained and that 87% of users feel working more independently. Those are very high numbers.
So the investment into customer education will most probably pay off, but if you're about to start or switch a documentation platform, definitely set up some metrics so that you are able to present your case to your upper management. On that topic, I can definitely recommend reading a book by Adam Avramescu called "Customer Education: Why Smart Companies Profit by Making Customers Smarter" or just read this excerpt about calculating ROI for customer education teams.
In any case, you'll try to minimize the costs. With that, the question will slowly change to, "Is there a way to get all the benefits from ready-to-use software while also receiving all the benefits from a custom solution?"
Content as a Service, Best of Both Worlds
The answer is yes, partially. There is a new trend in the content world, and that's Content as a Service (or CaaS). At first glance, it may look like building a documentation portal on WordPress or a different CMS, but the reality is different. The main advantage is that you can build your portal as if it was a custom one, so all the more advanced things are possible, but you're already building on something.
That something is an online service that will provide your content in the way it's needed, an authoring experience that can be configured heavily, and a set of SDKs that will make it much easier for developers to implement the portal. You don't get rid of all the hard parts of a custom solution—you still have a lot of planning to do—but using an existing CaaS solution can help you with the basic stuff.
For example, before creating the actual content in Kentico Kontent, you first define your content model. With that, you can ensure that the structure of documents is the way you want it to be and that the content is created with semantics in mind, not visuals in mind. That means you don't get drowned in setting the size of your text, its color, etc., which happens a lot with WYSIWYG editors, but you just say that this is a callout, this is a heading, this is a code example. Then the developers can set what all elements in your portal are going to look like. One of the advantages is also reusing certain content. You can use whole pages or just small chunks of text in different places. Say goodbye to callouts about premium or beta functionality, copied and pasted into many articles.
With CaaS, you'll get a full autonomy regarding the output. The CaaS software stores the content, but the displaying of the content is done by a custom web application (or an application for a different medium or you can easily have even more of them—one for web, one for a mobile app, both displaying the same content). If you want your customers to sign in to get even more personalized experience, you can do that. If you want to integrate with your sign-in service, you can do that. If you want to integrate with Google Analytics, Algolia, Optimizely, GitHub, Jira, Intercom or pretty much any service that has API, you can do that.
In addition to all that, there's one part of CaaS that will be interesting to those larger customer education teams. And that's the fact that CaaS can be used for training materials as well. Besides our documentation, we also use it as a source of data for our training courses for a different product. Now, when we think about introducing courses for Kentico Kontent, the automatic thought is that we could store the data in one system so that we can use the content in both documentation and training. That can simplify and therefore cheapen the administration around the created content even more.
I don't think we would have chosen to go into a CaaS software if we weren't vendors ourselves. That's because this trend is new, and we probably wouldn't know about it. With more and more businesses coming to CaaS for their documentation purposes, I believe that this trend is the next main thing for documentation, at least from the infrastructure and organizational point of view.
Going further with 3rd party solutions would definitely have been a way to go, but in order to continually improve the users' experiences, going custom was our long-term thought. With the CaaS software emerging on the market, it's an interesting alternative that gives you the freedom of a custom solution but decreases the complexity of it.
Thanks to choosing Kentico Kontent, a Content-as-a-Service software, we were able to implement many integrations that would have been complicated otherwise. Check out our next article that will go deeper into our requirements. We'll tell you about our design of the content model and integrations, introduce a case study of our experience, and mention what we plan for the future.