Stories linking everyone in Telecom
PortaOne Documentation Story Cover Art

PortaOne Documentation Portal: Growing from One-PDF-Fits-All into a Modern Knowledge Base

Table of Contents

“Documentation is a love letter that you write to your future self,” Damian Conway once wrote. Besides manifesting our love to our customers, PortaOne Documentation is essential in helping customer teams understand and implement our products’ new features and concepts. Some people attribute the quote “Any product that needs a manual to work is broken” to Elon Musk. However, Tesla has a manual embedded into its instrument panel, and so does Starlink. Therefore, if the quote attribution is correct, Mr. Musk might have a double-standards problem (again).

B2B products need manuals for many reasons. Primarily, good documentation defines successful product implementation in B2B (and any SaaS business model in particular). Despite that, while consumer electronics has landmarks such as Apple DD and Google Cloud Documentation, it is much harder to find those in B2B. However, people still manage. Catherine Heath wrote this excellent text in (now) distant 2017. Among other cases, she mentions Marvel APl and The Hitchhiker’s Guide to Python.

Today’s story explains how our documentation process evolved, culminating with the PortaOne Documentation Portal in 2022. While drafting this story, we tried putting the documentation process at PortaOne within the global context of how the best product documentation practices have evolved worldwide.

The Early Days of PortaOne Documentation: At Least README.txt Was OK

A README.txt file is a standard convention in software development and other technical fields. This simple text file typically contains information about the project or associated software (thank you, ChatGPT). Historically, READMEs were the first product documentation before the marketing folk and technical writers arrived in the field.

Here’s a different type of README.txt story. PortaOne documentation is not as revealing and controversial as the one leaked by Chelsea Manning (formerly Spc. Bradley Manning). Nevertheless, at PortaOne, we do our best to uncover all the secrets and gems of PortaBilling software. 

The typical structure of a README file includes a product description (“what does it do?”), installation instructions, possible use cases for the software, and a configuration explainer (“how to tweak the way this software works”). Additionally, for open source software usually includes license information (what the user should and shouldn’t do with the software) and guidelines for anyone willing to contribute (i.e., modify and write new code).

The first recorded use of README.txt (according to Google) was on November 27, 1974. Authored by Ashley Grayson (by then marketing and sales manager for DEC), it ends with “Good luck!” We discovered this by stumbling upon a Medium post about README by Omar Abdelhafith. In his turn, Omar discovered Ms. Grayson’s README by reading this StackOverflow thread. One of the possible explanations for the origin of the “README” name comes from Lewis Caroll’s Alice from Wonderland and is an allusion to the magic munchies from that tale labeled “Eat me!” and “Drink me!”

Alice in Wonderland inspired not only the name of README.txt (more recently: if you use shared code repositories like GitHub) but also a whole bunch of high school animation projects like this one and a section of this blog post on PortaOne documentation.

What Did the First PortaSwitch README Look Like?

“Because PortaSwitch originated in the late 1990s when business software product documentation was already an established field, and because our primary target audience was business owners (or engineers turned business owners), PortaOne never had a classic README.txt. We launched straight into stage 2, which is PDF manuals,” explains Andriy Zhylenko, PortaOne CEO.

The Manuals Era of PortaOne Documentation

As computer software broke out of its “geek niche” to a larger consumer market, simple READMEs were not enough anymore. That’s when the old good owner’s manual (like the one in your grandad’s car) came in handy. Writing for UX Collective, Ukrainian-Canadian author Olesya Vdovenko wrote a great story on the evolution of user manuals, guiding us from the cuneiforms on limestone tablets of Ancient Mesopotamia to the AR of Google’s Street View.

IKEA is well-known for its textless manuals. This short film by Lucidchart explains the story behind those manuals and the reasons for their success. On top of that, Dutch interactive artist Vibeke Bertelsen came up with funny AI-assisted ways for creating fake IKEA manuals for literally whatever, from French kissing to setting up Donald Trump’s hair. We can only wish PortaOne Documentation was textless as well. Do you think this is possible? Contact us with your ideas at 

Of all possible user manuals, this one by Google, explaining how to use Earth, might be the most hilarious. Notice that it’s a set of articles from Google’s knowledge base, presented as an “earthling’s manual.” Our favorite is “Discover places and change your view.” 😉 Indeed, people who tend to discover new places often have a broader life perspective.

How PDF Manuals Were the Early PortaOne Documentation

In the early 2000s, many people became obsessed with PDFs. Although PDF was invented in 1992, its golden age arrived in the late 1990s. With the mass adoption of Office97 and its WordArt, PDF offered a counterbalance with its smooth, crisp, and professional print design. Many businesses (including PortaOne) relied on PDF to distinguish themselves from the competition.

Are you old enough to recognize this text-styling utility? Some of us doing PortaOne documentation do. Interestingly, the “PDF movement” appeared as a designers’ revolt against the simplified visual esthetics of WordArt, yet many of the same people are nostalgic about it now. You might be delighted to discover that Scott Forstall (later one of Apple’s top software engineers) invented WordArt with Nat Brown in 1991 while interning for Microsoft.

The oldest PDF manual we have in our online archives is the Administrator Interface Guide for Maintenance Release 10 (2006) of PortaBilling 100 (a brand name for PortaBilling at that time; “Series 100,” pretty much like Nimbus 2000 — it made the product sound more “established”). If you want to know more about our maintenance releases (or, put briefly, “MRs”), there’s a story from this blog covering it. Since MR14 (2006), we’ve also introduced a separate PDF titled “The New Features Guide.” 

With time, PortaOne documentation grew from a single PDF into a constellation of over seven document types. Each was regularly and diligently updated each time we released a new MR.

Regarding the Nimbus 2000, Andriy Zhylenko recalls: “We revamped the code and features of PortaBilling around 2006. The latest version of PortaBilling generation 1 was around 2.3. Before releasing the new gen 2, we sat with the Captain to figure out the naming. We settled on PortaBilling 100 to emphasize that it’s completely different from the previous version.”

The First Dedicated Tech Writer at PortaOne

While Andriy Zhylenko enjoyed being the PortaOne tech writer, with time he realized that it was too much for the company’s CEO to take on. To the dismay of the PortaOne team, in the 2000s, good technical writers were a rare species in the Ukrainian tech ecosystem. (Frankly, they still are.) “This position requires (1) a profound understanding of our products and underlying technology; (2) sound command of written English; and (3) being able “to wear the customer’s shoes,” in other words, business empathy. With this skill set, you are looking at another CEO,” Andriy jokes.

With the option of hiring somebody from the market unavailable, PortaOne management started an internal search for a tech writer. Luckily, they soon discovered ​​Yaroslav Fedorina, who had worked in our customer support for over three years by that time.

Yaroslav became the PortaOne technical writing lead in 2013. He introduced PortaOne to RoboHelp, which was part of Adobe at the time. RoboHelp was the critical platform for PortaOne documentation until 2021, when we started experimenting with various other solutions. (And we still are experimenting as of the time of this article.) Being part of Adobe, RoboHelp provided various exporting tools for PDF and Flash.

The New Features Guide

“After some time, we decided a PDF guide wasn’t enough. Therefore, the New Features Guide appeared,” explains Mr. Zhylenko. Fast-forward a decade, and the New Features Guide (NFG) became the most loved document for all sides of the business equation: PortaOne project and product managers, customer support professionals, and our customers.

“In the late 2000s, we developed certain visual conventions for our New Features Guide,” explains Alexandre Starovoitov, art director at PortaOne. Here’s a look at some of the PortaOne documentation icons from the Golden Age of our PDF guides.

The NFG served two purposes. First, it provided an overview of what to expect from the upcoming MR. Second, it was a marketing instrument that helped customers who were hesitant about upgrading to a newer MR make the right decision. “The NFG became one of the key instruments for our customer communication,” explains Mr. Zhylenko.

Engineers are usually marketing-proof folk. They prefer reading actual feature explainers from an upcoming release, not a landing page that lists product benefits. NFG helped PortaOne build this type of “no-BS” customer communication. By the way, NFG has survived into modern times as a “What’s New” section of the PortaOne Documentation Portal.

Granularity, Knowledge Bases, and Documentation Portals

Gerrit Muller, the Norwegian author and systems engineering professor, advocated granularity in product documentation as early as the 2000s. Granular documentation has existed since PDP-10 and the early BBS chat rooms. However, it took decades for another critical beneficiary in the ecosystem of granular documentation to appear and beef its indexing muscles.

Daniel Waisberg conducted this interview (see timecode 7:37; also available as a blog post) with Google’s technical writer Rick Eliott in 2016. However, the lifecycle of Google’s help center article is still valid. We used Google’s tech documentation process as inspiration for the PortaOne Documentation Portal.

When did you last open a product manual to help with a task? Google changed the content marketing game: if you don’t find a handy answer within milliseconds (and its search results), a competitor steps in. This situation, in turn, might lead to you losing a prospect just because your business relies on an “old good one-PDF-fits-it-all” approach.

Google has profoundly changed how our generation does business – while also doing some nasty things. We could say that Google created the lifestyle of the modern content marketing specialist. Being able to note down these philosophical considerations in a blog post on PortaOne documentation while spending time with family on vacation from the army is a great demonstration of this fact. And, of course, we do it in a small text YouTube video description while mentioning the focus keyword. The PageRank game has to be optimal, no matter what. 😂

By now, documentation portals and knowledge bases are the business standard. There are gazillions of decent guides on how to create one. In this story, we’re sharing our experience building and launching the PortaOne Documentation Portal. We leave it to you to decide which of these practices are worth following.

An Occasional Encounter That Led to Massive Changes in PortaOne Documentation

“Around 2008, I encountered my first B2B knowledge base. That was Zendesk,” recalls Andriy Zhylenko. He discovered it not by googling “Zendesk knowledge base” but by looking for some business-related answer. Besides being a powerful sales instrument, an online knowledge base was easy to discover for Google’s indexing bots and very helpful to the end user.

With PDF, you have to perform multiple complex actions: download a PDF file, open it, click Ctrl+F for the relevant search term, and figure out the context and the scary acronyms the text uses. The knowledge base article written straight on the subject in native HTML bypassed all that. You just got the answer to your question neatly highlighted within the text. However, from the business owner’s standpoint, this knowledge base heaven comes with certain strings attached.

The Challenges of Switching from PDF Guides to the PortaOne Documentation Portal

Here, we summarize those challenges in an HMW format, once popularized by the Nielsen Norman group. Therefore, how might we:

  1. Create the semantic structure of the knowledge base so that it is easy to read and understand.
  2. Migrate from a single offline PDF document to an online portal with hundreds of smaller HTML-formatted documents.
  3. Make the new atomized structure autonomous, i.e., understandable without reading the entire 20 pages of PDF.
  4. Preserve formatting and the visual conventions we developed over two decades of authoring our PDF documentation.

We asked our AI friend to answer these questions as well. You can check out the results and compare the human-generated HMWs to computer-generated ones. While drafting this section, the tech writing team agreed it deserves a separate video podcast on your YouTube channel. And this brings us to the next part of today’s documentation story.

Ms. Zablotski and Our Shift Toward Video Tutorials

Tanya Zablotski is our project manager and the locomotive behind the new PortaOne approach to modernizing product documentation (and shifting from text-only to video format). Being Barcelona-based, Tanya has direct access to all the top management, and from there, she did a great job of slow but determined management education towards embracing the modern approaches to documentation, features marketing, and interactive storytelling.

Tanya moved around the world from her years as a schoolgirl until she decided to settle in the beautiful and bilingual city of Barcelona. “I always wanted to know more, in particular—to speak more languages,” she explains during a Zoom interview. The passion for “knowing more” shaped Tanya’s future. “I usually try watching TV movies and reading news in the language I’m currently focused on. In the 1990s, that was cable and satellite TV. In 2005, it became YouTube.”

Auf Deutsch gesagt! is an excellent example of the YouTube channels Tanya Zablotski uses while learning a new language (German, in this case). This experience helped Tanya define and create the video dimension of PortaOne product documentation.

From her early teenage years, Tanya tutored English to her peers. “Knowledge acquisition has become my passion since then,” she smilingly states during our interview. This passion became handy when the PortaOne marketing team noticed that brief video tutorials created many conversions from customers and prospects compared to PortaOne documentation in text-only format. Tanya decided to try it and released her first PortaOne video tutorial.

Tanya Zablotski did a great job of turning PortaOne documentation into neatly structured YouTube video courses, like this one on carrier management. Visit the playlists section of the PortaOne YouTube channel for more video courses by Tanya and her colleagues.

PortaOne Video Courses Skyrocket 🚀

“YouTube courses turned out to be a total blast for our existing customers and prospects,” explains Roman Khalenkov, chief commercial officer at PortaOne. Tanya’s video courses come in a new format — short, three- to seven-minute snippets neatly focused on common business scenarios and sorted into a playlist. “The structure and detailed video descriptions allow the viewer to decide whether to watch or skip the clip. It saves time and keeps the viewer focused,” Ms. Zablotski explains.

Tanya’s fame as a rising PortaOne YouTube influencer did not leave our top management indifferent. Therefore, Andriy Zhylenko launched his 101 course on authentication, authorization, and accounting (a.k.a. “the triple A”).

A video course on authentication, authorization, and accounting (AAA) by Andriy Zhylenko is part of a more comprehensive PortaSwitch 101 initiative providing PortaOne documentation in a new format, which might be more convenient for our younger (or simply lazy to read) customers, prospects and future employees.

PortaOne currently has several upcoming YouTube courses in production. Meanwhile, while drafting this story and interviewing our video creatives and production team, we decided they deserve a separate blog story. Stay tuned!

The Team Behind the PortaOne Documentation Portal

The story of the PortaOne Documentation Portal is only possible because of the people who create and improve it daily. Our current documentation team is distributed among Barcelona, Chernihiv, Nizhyn, and Sumy. 

This screenshot captures Team PortaOne Documentation at work. Here, they discuss future changes to the PortaOne Documentation Portal in an online call: Tanya Zablotski (Barcelona), Anastasiia Holota (Nizhyn), Anna Kruhliak (Sumy), Tetiana Savchenko (Chernihiv), and Alisa Rieznikova (Sumy).

The Great Global Tanyas’ Conspiracy

On a Zoom call with Tetiana Savchenko and Tanya Zablotski, we joke: “You have to be Tanya to lead PortaOne documentation.” Ms. Savchenko contributes from Chernihiv, and Ms. Zablotski (as mentioned above) from our Barcelona office. Given that the PortaOne head of marketing is Tatiana Massalskaya — the global “Tanyas’ conspiracy” starts taking shape. For those not illuminated in the Eastern European naming conventions: “Tanya” is short for both Tetiana (Ukrainian) and Tatiana (Portuguese, Romanian, Spanish and many other languages).

“Creating the New PortaOne Documentation Article” Flow

Ms. Savchenko outlines her vision for the routine of creating a new PortaOne documentation article: 

  1. Kickoff meeting
  2. Getting the early “bullet points”
  3. Creating the mindmap (before it was MindMeister, now Miro)
  4. Wireframing the visuals
  5. Creating the story structure
  6. First draft
  7. Peer review
  8. Product owner review
  9. Proofreading by the native speaker
  10. Publishing to the PortaOne Documentation Portal

The PortaOne Documentation Future Is Here: Robot Assistants and Customer Co-Creation

It’s funny that to build a successful robot assistant, thus “replacing” (a popular stereotype) the human beings in customer support, the willing business has to invest thousands of man-(or woman)-hours into creating clear and coherent product documentation. In this way, “a machine” will understand enough to answer questions from other humans.

“Our bottleneck currently is not the AI chat technology but the amount of hours our senior architects and developers can commit to authoring PortaOne documentation, thus making those robot assistants possible,” explains Andriy Zhylenko. That’s why we are working on new hires and growing a new generation of in-house authors of PortaOne documentation via the PortaOne Education Program.

Mike Kidik explains updates to the PortaBilling API during our recent PortaOne Barcelona Meetup. Our code and PortaOne documentation will intermingle even further, bringing new opportunities for using machine learning and feature automation.

People keep asking me, “Aren’t you afraid that %chatGPT, Gemini, Copilot% (or whatever the current fancy AI model out there) will make your job as a technology marketing copywriter irrelevant?” No, I’m not afraid. Most of the time budget spent on each of the stories for this blog is research and interviews with subject matter experts and fact-checking with the first-person witnesses of the events. The same is the case with PortaOne documentation. Oh, and I also spend tons of time inventing jokes very few people (or AI models) understand.

Customer-Made Low-Code Features

One can compare low-code to what the open-source movement did in the late 1990s. However, back then, active participation (that is, actually delivering products, not merely installing software, buying books, and funny t-shirts) in the open-source community was limited to people who could code. 🤷🏼‍♂️Low/no code is changing all that with its drag-n-drop, RAD, and workflow automation.

Watch Oleh Shevtsov and Sergii Kirik (protagonists of one of our previous stories, BTW) share their ideas on a no-code solution for MVNOs.

“I see customer co-creation as the next level of customer support at PortaOne,” explains Oleh Shevtsov, head of the project management department at PortaOne. Indeed, in B2B SaaS, the concept boundaries of “the customer” are becoming more fluid each year. Every business sells something to the other, with established IT giants merely providing a platform for those interactions.

The Further Conversation

Do you have ideas and suggestions on how we could improve PortaOne documentation and our Documentation Portal? Are you interested in joining our team and creating product documentation that amazes your colleagues and customers? Please pitch us at or via any digital channel that is convenient for you.

Share this story

Related posts