All public-facing product documentation for Zendesk is published in this Zendesk help center. Though most other teams at Zendesk create content directly in the 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.
This article covers the following topics:
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).
How we publish to the 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.
Starting with version 24, Oxygen XML Editor includes a built-in transformation scenario that can publish DITA topics to XHTML output and upload them directly as articles to a Zendesk help center. See DITA Map Publishing in XML Editor help. For a video, see Publishing Content to Zendesk Help Center in XML Editor help.
Occasionally, we need to update many articles in a short amount of time. For example, when Zendesk simplified its pricing and branding, hundreds of amended articles had to be published by 8 a.m. Pacific time on a specific date. In the weeks leading up to the deadline, the writers updated the DITA source files, then we batch transformed the files and pushed them to the 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 the 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.
Hi Valery, unfortunately we don't have a script for the use case I'm describing. Our team publishes articles manually.
To track which article in Help Center that a DITA file corresponds to, we use the `props` attribute in the top-level `topic` element of a DITA file to store the article id of the Help Center article. The writers manually add the id to the element when they publish a new article. Example:
Hope this helps.
Are there any examples of what this looks like? We are looking for a solution to publish our DITA manuals into an HTML format and this looks like it may work.
Wondering what the output is for a full manual with lots of cross references.
I took a different approach, probably more complex:
With media files stored in zendesk it takes quite a while, but if you use aws like @... proposes - it's much quicker and takes just couple of minutes for 300+ articles
Sound interesting they way you have done it. So you are able to manage the structure as well with subsections with pretty straight forward process.
I am not so familiar with Oxygen yet, so my questions might seem simple, but I would greatly appreciate insight on these.
You can add hierarchy in the documentation as elements like category, section, subsection, subsection directly on Oxygen side, and then update (create, update, remove) categories and sections/subsection accordingly with single "run"?
How much Oxygen expertise and development/configuration work this has required on Oxygen side to implement such process?
Thanks in advance,
Please sign in to leave a comment.