How product docs are produced at Zendesk

All public-facing product documentation at Zendesk is published in branded Help Centers. Though most other teams at Zendesk create content directly in Help Center, the Docs team creates and maintains the product documentation offline in DITA source files. DITA, which stands for Document Information Typing Architecture, is an XML-based data model for authoring and publishing content.

Note: The product documentation is different from the developer documentation on developer.zendesk.com. A different process is used for the developer docs.

Topics covered in this article:

• Why DITA?
• How we publish to Help Center
• How we manage files
• How we publish localized articles

Why DITA?

DITA is an industry-standard for creating and maintaining large documentation sets. Jacquie Samuels on techwhirl.com describes the problem it tries to solve as follows:

Writing content in Word, email, PowerPoint, WordPress, HTML, InDesign, FrameMaker, or any other format is equivalent to writing on stone tablets. Your content is essentially stuck in that format and dumb as a rock. Dumb content can’t be easily reused or repurposed, and that’s inefficient and costly.

DITA is a way of writing and storing your content so you can manage it like an asset. It leverages XML (eXtensible Markup Language) to make your content intelligent, versatile, manageable, and portable.

For example, content that is in DITA can be published to (and fully branded) PDF, HTML, RTF, PowerPoint, and mobile–all without ever copying and pasting anything between files.

(Source: What Is DITA? on TechWhirl)

Apart from separating content from format, the other benefits of DITA for the Zendesk Docs team are as follows:

• Forces us to be disciplined about content structure. A DITA file is XML. If the structure is invalid, the tool won't let us do anything with it.
• Allows us to move content around easily. We just drag a topic node from one place to another in the structure.
• Allows us to reuse content by importing chunks of content in multiple articles.
• We don't often publish PDFs but when we do, we use the DITA source files.

The DITA authoring tool we use is Oxygen XML Author. In addition to its robust authoring environment, we rely on a host of other features, including file search, file diff, change tracking, and HTML transformations. Other DITA authoring tools include Framemaker, Arbortext, and XMetal (to mention a few).

Note: Be aware that DITA has a steep learning curve in terms of both setup and authoring.

How we publish to Help Center

We use Author to create or update content in DITA source files. When we're ready to publish (usually at the same time a product feature is released or updated), we transform the DITA to HTML, then manually paste the source HTML into the article code editor in Guide. What the process lacks in elegance it makes up in simplicity.

Occasionally, we need to update many articles in a short amount of time. For example, when Zendesk rebranded the Outbound product to Connect, all the Outbound docs had to be updated at 7 a.m. Pacific time on a specific date. In the days leading up to the change the writer updated the DITA source files, then we did a batch transformation of all the DITA files and pushed them to Help Center using the Zendesk API. Publishing them only took a few minutes.

The batch-publishing tool we used is open source on Github for anybody to use. See https://github.com/chucknado/zpu. For instructions on how to use it, see the readme at https://github.com/chucknado/zpu/blob/master/README.md.

How we manage files

We store the DITA files in a Google Team Drive, which syncs the files automatically to each writer's computer. The writers always have the latest versions at their fingertips. When one writer saves changes to an article, the changes are immediately propagated to the other writers' computers through Team Drive sync. Team Drive also keeps any changes for the last 30 days. Again, the goal is to keep the process simple.

We also store images in the Google Team Drive but upload them to an Amazon S3 file server to make them available publicly. All the images in our articles are downloaded to your browser from S3, not from Help Center. The Amazon S3 service makes managing the images simpler.

How we publish localized articles

The default language of our Help Centers is English. We also publish the product docs in German, Spanish, French, Japanese, Korean, and Brazilian Portuguese.

When a localization handoff is due, we use the Help Center API to download selected English articles from the Help Centers and write them to HTML files. We use the Amazon API to download article images from our Amazon S3 bucket. We package the files and hand them off to our localization vendor. After the vendor returns the translations, we upload the articles and images with the Help Center and Amazon APIs.

The API client we use to manage handoff files is called ZLO (Zendesk localization tools), which was created internally by the Docs team. The ZLO client is open source and available on Github at https://github.com/chucknado/zlo. You can read more about it in the documentation on Github.