Zendesk is powerful and versatile. The longer you use it, the more tweaks and customizations your instance will undergo to align with your company’s customer service strategy and ad-hoc business requests. Documentation serves as a roadmap, ensuring that every modification – be it a small change in a macro or a major overhaul of your automations – is traceable, understandable, and easily reversible if needed. 

The practice of tracking and documenting Zendesk customizations and changes helps everyone on the team stay on the same page (especially when a new administrator joins). But more importantly, it significantly reduces the risk of disruptions caused by a faulty change. 

This is particularly crucial for enterprise-sized companies, where the scale and complexity of customer support simply can’t afford the admin team the luxury of spending hours troubleshooting a bug in their production instance. We heard a few horror stories from the field about quick undocumented changes leading to major support disruptions. There was nothing "quick" about them after all.

The dark side of documenting your changes

I don’t know a Zendesk administrator who wouldn’t agree with all of the above. 

But the challenge with documentation is… it’s hard. In the absence of native tools in Zendesk that could automate this process, change documentation requires time, dedication, and lots of leg work.

Usually, an admin team will have a spreadsheet where every change should be logged into in a descriptive manner: what configuration element(s) was changed and why, who and when made the change, etc. Administrators sometimes forget to do that or decide that certain changes are too small to warrant a log (spoiler: they are not). 

I’m sure you wondered if there’s a better way to do that without putting in so much work. Yes, there is!

Here at Salto, we came up with a solution that ensures that every change made in your Zendesk configuration is well documented – and it requires almost zero manual work from your team for that to happen.

‍

Automating change documentation in Zendesk with Salto

But first things first: if you’re not familiar with Salto, it’s a DevOps platform for business applications like Salesforce, NetSuite, and Zendesk, that helps administrators revolutionize how they make, deploy, document, revert, and track configuration changes. You can explore all those use cases here; in this article, I want to focus on the documentation piece of it.

Once you connect your Zendesk environment to Salto, it will start fetching your configuration with hourly, daily, or weekly frequency, depending on your account settings. Salto fetches don’t include any customer data or sensitive information from your Zendesk account, we’re only fetching configuration elements: Automations, Views, Triggers, Ticket Fields, Custom Objects, Brands, Business Schedules, and such (the full list is here).

After the first fetch, your Explore tab in Salto will populate with a detailed view of your entire configuration:

‍

‍
The real documentation magic starts after that. If with the next fetch, Salto detects any modifications from the previous fetch, it will add them to the Version Control tab for you to review:

‍

‍

It doesn’t matter if you or one of your teammates made that change using Salto or directly in Zendesk, it will appear in this list.

We call them commits. You can open each commit and see a side-by-side diff view of what was changed:

‍

‍

The more often you do that, the more granular each commit will be. We recommend doing it after each big deployment, but ultimately it’s up to you and your documentation strategy. 

Now, the Git part. If you’ve never used Git (or a similar version control system) before and don’t know much about it, don’t be discouraged. Our integration with Git is beginner-friendly and requires no specialized skills beyond opening an account with any Git provider and creating a new repository. 

If you already know your way around Git, you will enjoy this feature even more.

Once you click push inside a commit, your change will be documented in Salto and also saved in your external Git repository:

‍

If you want to go a step further, you can also record your change in your ticketing system: Jira, ServiceNow, or whatever you use for Zendesk requests. Connect Salto to your ticketing software and just add a relevant ticket number in the title or description of your commit – and Salto will automatically append the link to your detailed change to the ticket. That’s where things really come together: now you’re preserving a record of the stories around how things were built and why, which new users can find and read. And you closed the loop on that request.

‍

I timed myself doing all of the steps and it took me three minutes to document over 15 configuration changes made in our Zendesk instance. Amazing, right?

If I ever need to revert any of the modifications I made, I can quickly find it in Salto and roll back to the previous version of my configuration, without having to undo these changes manually. But that’s a story for another article. Stay tuned!