How I Chose My Documentation Authoring Tool
We all have stories about the tools we use and how we got there. I thought I’d share my story of how I ended up using Paligo.
My Journey toward Paligo
It was November of 2017 and I had just landed a fantastic new job. I was now in charge of documentation at a startup, working with an amazing team. But there was a fly in the ointment. Zendesk. The company had written and posted/hosted all their documentation in Zendesk. They ran all of Support through Zendesk. The two were heavily linked.
Ah, the challenge of working in native Zendesk.
Now, Zendesk is good at what it does, but it is most definitely NOT good for full-on documentation authoring and management.
I’m detecting a lot of nodding from fellow writers, but also some folks who maybe don’t agree. Here’s the analogy I shared with my boss:
What if you were to tell our developers that they have to use Windows for an OS, and for an editor they have to use Notepad, circa Windows 98? Then, tell them they can’t use #includes, search/replace, variables, or version control.
Could they still do their jobs? Probably.
Would they be productive? How error prone would the code be? How bloated would the processes become? How happy would they be?
Now tell whoever’s still working here that they have to update a value contained in 50 files. Because they don’t have variables OR search/replace, they have to open up each file and look for the value by scrolling through the code. (This is a real-world task — I had to do it in our Zendesk documentation.)
Oh, and what if when they wrote code, the editor tried to “fix” mistakes silently rather than letting them know it didn’t compile or run?
That, dear reader, is life for a writer using only Zendesk to author, maintain, and manage documentation.
And that’s why I wanted to move to a robust editing platform.
Alas, there’s a saying about a road paved with good intentions…
Finding Paligo
I looked around and (due to many factors, including the Support systems already in place and the preferences of existing teams) decided I needed a tool that could output to Zendesk rather than move the docs off of Zendesk.
This was a pivotal decision and one I’m kind of regretting. On the one hand, it meant that all of our existing Support Stuff (autogenerated emails with links to relevant docs, etc.) continued to work, with no changes required and I would not have to find a place to host the documentation. On the other hand, I would have to work with Zendesk’s restricted/rigid format for docs. We only get three levels of organization: Category, Section, and Article, for example. Our competitors are using fancy HTML5 help centers and static site generators with a “docs as code” approach, and to be honest, we look like we’re a generation behind.
I did look at several different options, from the new school “docs as code” static site gen approach to the old reliables: FrameMaker, Flare, and Oxygen. But the folks on the team were wary of leaving Zendesk and so we moved forward with Paligo.
Paligo has version tracking/branching, a powerful editor, variables, search/replace, reusable content, reusable content usage tracking, and a host of other Help Authoring Tool (HAT) functionality/features I haven’t even used yet. And yes, it exports to Zendesk.
Rough Edges
Now it’s late January of 2018 and I’m starting to think that sticking with Zendesk was a mistake. The Zendesk import to Paligo led to a LOT of work cleaning up the messy HTML we had created in Zendesk. Plus, there were some rough edges to deal with: the discovery that Paligo didn’t (at the time) support cross-category links, and the fact that there are these placeholder “Section” articles which are ugly and serve no purpose (plus, they do not work well with promoted articles). I started to get some heat from my coworkers who saw the staging area: the placeholder articles were a waste of time and diluted our SEO, the code syntax highlighting was gone, the CSS was ugly, etc.
Pushing Through
But thanks to the tireless Customer Support team at Paligo, I pushed on and managed to get the whole doc set imported and set up for publishing. I calmed fears and overcame objections. I wrote to Paligo Support and read Zendesk help center articles. At the end of the day, our documentation was better off and I was able to do more work in less time. It was a good thing.
I was feeling exhausted but also felt like I had crested the hill and that it was all smooth sailing from there…
There’s a saying about the best laid plans…
Disaster
It’s the middle of the afternoon and I’m in full panic mode. When it came time to switch over from testing to production, I broke every URL. Yes, I completely missed that the new articles would have new URLs. To be clear, this is NOT Paligo’s fault! I simply dropped the ball and made a mistake.
I had the product folks coming to me, the CS folks, the SEs, and the SEO/web team, all wondering what had happened and when I could fix it. I had broken a LOT of stuff (the product UI, links in the website, the links the teams sent to customers, Google search results, etc.) by basically invalidating every URL.
The Team
This is where having a fantastic and supportive team and matching culture came in to play. The team here is fantastic and the culture allows for experimentation and making mistakes. I can’t say enough about how great the team is. People pitched in to help me remap the URLs. Some folks just stopped by my desk to ask if they could help. We got the mess cleaned up quickly and I could finally relax.
The Results
Today we have our docset in Paligo, publishing out to Zendesk. There are still some warts (those painful, extraneous placeholder articles are the bane of my existence). I occasionally find places where Paligo’s Zendesk output support lags behind their HTML5 output; however, Paligo’s support is top notch and they come through with a quick fix or update every time.
I still have a long way to go in getting our documentation to be as useful and helpful as it should be. The good news is the authoring platform is no longer part of the bottleneck.
Choosing an authoring platform will always mean picking your battles, making a few compromises. For me, I went heavy on the tool/functionality side, knowing that I’d have to live with some funkiness with the Zendesk support. Others would have made different choices. Some folks don’t mind doing a lot of configuration and setup, working with opensource tools. Others prefer a seamless integration with the output.
For some of us, budget is more of an issue, and for others it’s control.
Would I do it all again? No.
I wouldn’t publish to Zendesk.
I still wonder if moving to a more modern docs framework/format would have been the right call. But do I regret using Paligo? Not a bit! Despite all the pitfalls and mishaps along the way, the one thing I was sure of was that Paligo was the right call.
