Blog // Bonnes Pratiques

5 Myths about Technical
Documentation Publishing

Jan 27, 2022  |  Reading Time: 7 minutes

The technical documentation every company owns is a major reserve of business opportunity. But when it comes to publishing that technical documentation, many myths abound.

Those who believe these myths cannot realize the full value of their documentation and therefore miss its bottom-line benefits.

Let’s look at 5 myths and unravel the truth.

MYTH 1: A documentation portal is nothing more than a website 

It’s really so much more! Some of our clients have tried to manage their documentation on their own corporate websites to avoid the extra cost of starting from scratch and mutualize the development. The sheer volume of documents and the intricacies of this content made it almost impossible to properly manage. Without exception, they realized that in the long run, they needed to find a more appropriate solution.

So, what’s the difference between a “Website” and a “Portal”? Let’s take a closer look at the table below:

Website Documentation Portal
Definition A web-based solution that consists of web pages containing publicly available generic content A web-based solution that hosts specific, detailed, exhaustive content, that can either be public or restricted to specific users
Accessibility Accessible via URL Accessible via URL
May require authorization (logins)
Users General audience, can be differentiated by country Generic and specific users and user groups (i.e: customers, employees, resellers)
Admin and Publishing Managed by admin (Marketing or Web team usually) Managed and fed by multiple authorized users (Documentation teams or developers usually)
Communications and interactions Simple interactions (contact, subscription or download forms) Two-way communication between users and the documentation owners

Although publishing part of your documentation on your corporate website, such as product datasheets or the latest release note, may make sense, hosting your entire knowledge base on a static system, is a challenging endeavor.

For this reason, Content Delivery Platforms (CDP) have emerged to take product content publishing to the next level. Fluid Topics, for example, offers tech organizations a smooth user experience with their product through their smart documentation portal. Our solution provides you with the following key features and benefits:

  • Secured publishing from multiple contributors and sources: organizations can publish all their documentation, from all authorized content producers and from different tools and systems to their single knowledge hub, with the highest standards of security,
  • Authorization control: admins can manage identities, permissions, languages and more to ensure the right content is delivered to the right user,
  • Fast, personalized search and find: users get fast access to the content that is relevant to them, to their profile, and to their needs without the noise of millions of documents thanks to AI-powered search capabilities,
  • Interactivity capabilities: users can rate and save their favorite content, interact with it or even send feedback to the writers,
  • Powerful analytics: admins can see what content was viewed down to the topic level, and for how long, every keyword search, selected facet, most popular searches, searches with no results, and much more.

On top of that, our platform is built to exceed the most demanding industry standards. Our cloud-based architecture includes a comprehensive suite of services to guarantee availability, scalability and security. Something that we’re sure will make your IT department happy.

MYTH 2: Building a documentation portal is time-consuming
and expensive 

Obviously, if you’re reading this, you already know that a documentation portal is a key channel to have within your organization. In the age of digitalization, any company, selling software or hardware, will need a documentation portal that will serve the most up-to-date and personalized content.

Nonetheless, you’re now probably thinking about how much it costs and how long it takes to build a portal. Indeed, people have been made to believe that creating a documentation portal is a long process, requiring them to hire a developer that will charge an excessive fee.

Fluid Topics has a track record of helping companies quickly build rich content experiences through their documentation center. In complete autonomy, you can implement an out-of-the-box portal with all key functionalities and modules packaged in a comprehensive platform. You can also tailor the look and feel in just a few clicks using a variety of “drag and drop” components and a user-friendly WYSIWYG editor. Finally, you can add different types of pages, customize content, layouts, branding and other design elements to fit your needs.

The costs are significantly reduced since you only need a fraction of the resources necessary to develop a similar solution from scratch. Therefore, you can quickly scale your knowledge center without incurring massive additional overhead.

Page Designer

Not to mention that, with no additional effort or cost, our CDP natively provides your global audience with a portal interface in 23 languages. You can find the full list of supported languages right here.

“I localized the portal in 8 new languages, including Korean and French, in about 30 minutes. If I had to do it differently it would have cost us at least 30 000 euros »

said one of our customers, a global leader in measurement solutions.

If you’re interested, you can learn more about our documentation portal solution right here.

MYTH 3: I need to re-write my content for the different types of channels  

Digital transformation is not a hype anymore, it’s a reality! A 2020 article by McKinsey Digital stated that companies offering service experiences through digital channels had more loyal customers and could increase their customer satisfaction by 15–20%.

Organizations understand that they need to be where the customers are. They are embracing new digital channels. These digital options, web portals, chatbots, in-line help, or other online support channels, are key to providing an engaging customer journey and keeping pace with customer expectations… and competitors.

Documentation contributes to creating a high-quality customer service and you’ve probably been misled into thinking that you needed to re-write your content to fit all these digital touchpoints.

Our platform removes the burden of having to write your content in a specific format to fit the different channels. Fluid Topics collects and unifies all types of documentation, no matter the initial source and format. From DITA, Docbook and other XML-based formats, to HTML, Markdown and YAML, our set of processing pipelines ingest your content in its native format. Our solution then transforms all your information into granular, unified, digital-ready content and publishes it simultaneously to all these channels. No extra IT resources required.

Fluid Topics Platform

If you want to dig more into the topic, we have published a dedicated blog post “Come as You Are”.

MYTH 4: Technical documentation publishing slows down the product release process

Fast product release cycles are a fact of life in SaaS companies. Industry 4.0 has embarked on a similar journey. With small batch production, companies can make changes more easily with each version of their product. Thus, frequent product releases are the new norm and tech writers are now under pressure to deliver the latest documentation as soon as possible.

With new versions arriving every month, week or even day, the most common misconception is that it’s almost impossible to release new documentation in real-time and in-sync with the product update. People tend to think that the writing and publishing of brand-new feature documentation add days or even weeks to the process. Another misconception stemming from the first one is that it’s not possible to publish updates, enhancements and documentation fixes in-between version deliveries, continuously.

Moving to Dynamic Content Delivery is an effective way to keep pace with products as they change without letting documentation become a bottleneck.

Hexagon, a global leader in sensor, software and autonomous solutions has recently implemented a CDP. The company shifted to SaaS and faced a strong acceleration of the release pace. To that end, they needed to swiftly deliver technical documentation. They stopped publishing static PDFs that required lengthy formatting to publish dynamically to their Fluid Topics online portal. They decoupled the documentation from the product itself to allow for more flexibility and reactivity.

« We saved up to two weeks in the documentation delivery process and easily reached our goal of four-week release cycles »

said Lonnye Yancey-Smith, Executive Manager for User Assistance.

Nowadays, Hexagon updates their technical documentation as soon as they need without impacting the release itself and can publish it simultaneously to any channel. You can watch our joint webinar replay in which Lonnye shares her experience.

Another way to make sure your documentation keeps pace with your releases is to include it in your Continuous Integration/Continuous Delivery (CI/CD) pipeline.

Continuous Integration At Fluid Topics, we have a zero bug policy and therefore, we release bug fixes and new features on a weekly basis, and more often if needs be. It means that our documentation also has to be ready at any time. We have embedded the writing and publishing process of the release notes inside JIRA and GIT. The documentation is mapped with the release version. The Product Owners and Developers fill specific fields containing the content and indications related to the documentation needs. Tech writers review, complete and validate the content. Finally, a bot automatically publishes it in sync with the software rollout.

In short:

  • Developers and Product Owners work with their favorite tools
  • It’s all automated and manage by a bot
  • Nobody feels like there is a “Documentation” rush

MYTH 5: I need to write personalized content to deliver a personalized experience  

The web is moving toward increasing levels of personalized content. As a result, both businesses and end customers expect more today. They want contextually relevant, personalized, consistent content experiences.  According to the fourth edition of the Salesforce “State of the Connected Customer” Report, 52% of customers expect offers to always be personalized — up from 49% in 2019. On account of this, technical documentation is also expected to offer a personalized experience.

Companies have tried to deliver personalized content, usually manually, by creating different content for each customer type. In most cases, it just didn’t work. The reason lies in what Val Swisher calls the Personalization Paradox. “To provide personalized experiences at scale, the content must be standardized. Personalization should only happen at the point of delivery and not at the point of content creation.” Specifically, your content must be available as granular, small components that are tagged with rich metadata so that publishing platforms can assemble and deliver it in a personalized, contextual way.

Many companies have embraced standardized content creation and have converted their methods and teams to structured content writing. In numerous cases, they have set up rich taxonomies and implemented a Content Component Management System (CCMS), and made their content ready for personalized delivery. However, most organizations are still in the process of converting their content, or are required to maintain unstructured content, like Word documents, or additional content sources like Markdown files.

In both instances, CDPs are essential to achieve personalization and contextualization. To this extent, Fluid Topics connects to both structured and unstructured content sources, processes, chunks and enriches the unstructured content so that it looks like it was born structured. Once the content is unified, Fluid Topics delivers it to each user according to their profiles, preferences, but also to their behavior from which our AI-powered search engine constantly learns from.

Talend, one of our customers, has experienced the benefit of having a CDP. They have designed a strategy where access to content is highly contextual and personalized, entirely driven by metadata.

“Every piece of content is tagged at a fine-grained level: when it comes to DITA content for example, we actually tag at the topic level, not just entire books. This helps to add context for when a piece of content applies. Fluid Topics is uniquely capable of leveraging our fine-grained metadata to deliver an efficient search experience. »

explained Elisabeth Sabot, Senior Director of Technical Communication.

Businesses seeking to drive greater customer satisfaction and reduce churn will need to rethink their content strategy at the delivery point to effectively provide personalized experiences.

So what now? 

In the technical documentation world, many still have doubts about leaning towards a Content Delivery Platform, notably because they feel like there is so much work to be done before getting there.

We hope that by debunking these 5 myths, you’ll get a better understanding of Dynamic Content Delivery and how it can transform your documentation publishing. If you still have questions, make sure to check out the “6 things you really need to know about Fluid Topics” or get in touch with us!

About The Author

Anne-Sophie Lardet

Anne-Sophie Lardet

Anne-Sophie has over 10 years experience in product and digital marketing in fast-growing tech startups. Additionally, she has experience in UX design, social media, content strategy and marketing communications. She's passionate about helping start-ups understand, engage and support their customers.