“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.
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, README.md 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!”
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.
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.
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.”
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.
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.
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.
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:
- Create the semantic structure of the knowledge base so that it is easy to read and understand.
- Migrate from a single offline PDF document to an online portal with hundreds of smaller HTML-formatted documents.
- Make the new atomized structure autonomous, i.e., understandable without reading the entire 20 pages of PDF.
- 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.”
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.
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”).
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.
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:
- Kickoff meeting
- Getting the early “bullet points”
- Creating the mindmap (before it was MindMeister, now Miro)
- Wireframing the visuals
- Creating the story structure
- First draft
- Peer review
- Product owner review
- Proofreading by the native speaker
- 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.
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.
“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 sales@portaone.com or via any digital channel that is convenient for you.
