It was somewhere in 2019 that we decided that it was time to grow up and use a real documentation tool. Up till that point, we were using Intercom to create our knowledge base. Let me put that in context. It was like using Notepad to write a novel. Wait, what good is an analogy if we are going to stick to the general practice? So, let’s step out, shall we? A better analogy would be like using a cycle to commute to work. It wasn’t cool enough, so we decided we needed a car. Wait! What? How is that an improvement or cooler?
Whatever!
Over many discussions powered by innumerable cups of coffee, we settled on Paligo as the writing tool we would use. But just like deciding to move to commuting using a car when all you did earlier was pedal, this too needed some planning. Training, licenses, and all that stuff. But more importantly, it was a new way of life that we were about to embrace.
At that point, we had about 2500ish articles.
Step one was to move all our content over to Paligo. Intercom was like America in the 18th century, everything was black or white. It treated all content as either body or para. Paligo on the other hand divided the content into more nuanced groups. So once we ported the content, we spent a good chunk of time sorting the content into titles, paras, ordered lists, numbered lists, procedures, admonitions, and what not. To be honest, I did feel at times like the sorting hat at Hogwarts.
When you move from riding a cycle to work to driving a car, it is more than just a change in mode of transport, it is also a lifestyle change. You have more time to lounge in bed, romance the spouse, take up cooking, wear better clothes, smoke on your commute. I guess what I am saying is that it didn’t do to just move the content from one tool to another, we needed to make changes that allowed us to benefit from the features in Paligo. This meant revisiting the content. Some of it required rearranging, some restructuring, and some just needed to be trashed.
For instance, in the old system we have six articles telling the user how to collect payment on an invoice. The titles will help you understand why. Collect payment in cash. Collect payment using a credit/debit card. Collect payment using membership credits. Collect payments using custom payments. Almost 40% of the content was duplicated. This meant it was a maintenance nightmare and an expensive translation project. In our new world, we could condense them into one article titled Take payments.
Just when we thought we were done, we found a new villain - broken links. Yes, we technical writers love linking our documents, don’t we? In another lifetime, we were told that our articles had to be short, small, tiny. These little pearls would then be threaded together using the magic of links to create an expensive necklace. Expensive to whom? Our readers, who now had to jump through ten links to understand how to complete one procedure. Is it a wonder we are disliked more than the programmers who created the product in the first place?
Finally, we were ready to launch. It was my first time handling a project of this size. I admit, I was excited and scared at the same time. Anyways, we bit the bullet and set the site live. Our baby lasted all of about 4 hours in the real world. We hadn’t contended with cheat sheets that our customers had painstakingly put together for their own reference. These were made of up links to our documentation. All those links were now useless. The BCCI could have dropped Sachin Tendulkar and there wouldn’t have been as much uproar. We quickly gobbled up the humble pie and went back to the trusted cycle.
A mapping sheet was put together that pointed every link from the old site to the appropriate new page.
Now we were ready. Again!
A piece of advice here. Get ready for the pushback. Everyone who told you that your Help site was useless will now ping you to tell you that they want the old site back. Same with the ones who had said good things to you about your Help site. Basically, change is a pain in the ass.
There is a solution and I wish I had thought of this earlier – a good search engine. Since we started with analogies, let’s end with one too. The search that comes packaged with Paligo is a stick drawing in a cave when what you need is a Picasso. Trust me, invest in a good third-party search engine. Nobody cares about the tree-structured left-side menu, except you. Your users almost always get to the articles through the search. If your search is broken, your site is broken.
It’s been a hell of a ride and it isn’t over yet. Like all good summer blockbusters, this one will have a sequel or more. This was just the first step in creating the kind of Help system of our aspirations.
Stay tuned for more travails and tribulations of a technical writer.
Postscript: My aim for 2023 is to commute 150 days on my cycle. Yes, while my Help system goes one way, I am personally moving to a simpler, less carbon-intensive life.
Commentaires