English (US)
  1. Zendesk help
  2. Guide
  3. Using Guide
  4. Using the knowledge base in Help Center

How product docs are produced at Zendesk

Charles Nadeau
  • Edited

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?

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.

Have more questions? Submit a request

12 Comments

Sort by Date Votes
  • Ann Jensen
    Comment actions Permalink

    Hi Charles,

    Thanks for all that information. I have successfully completed the following:

    - Published my DITA topics to HTMLS in Oxygen Author

    - Batch created Zendesk Guide articles from these using the files you shared on GitHub (Batch-publish transformed DITA files to Help Center)

    - Batch updated the same files

    However, I am still at a loss as to best approach for managing images. My DITA source is managed in SVN and the image paths are relative to this. I see you suggest using tools like Amazon S3 and Cyberduck for managing Zendesk Guide images but am unsure of the process. Are these images protected behind authentication or are they public?

    At this point I can't even successfully call the Create Attachment API as I get a 500 response code for no apparent reason.

    Can you advise?

    Thanks in advance,

    Ann

    0
  • Charles Nadeau
    Comment actions Permalink

    Hi Ann,

    We don't use any image attachments in our articles.

    We upload the images separately to a folder on Amazon S3 using the Cyberduck FTP client. Amazon s3 is a web server so all the images in our S3 folder automatically get published to the web.

    All the files on S3 get their own URLs. Our URLs all share the same path:

    • https://zen-marketing-documentation.s3.amazonaws.com/docs/en/image1.png
    • https://zen-marketing-documentation.s3.amazonaws.com/docs/en/image2.png
    • ...

    We use these URLs directly in the DITA source files for the articles. Example:

    <image href="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/image1.png"
id="image_kgv_5xy_np"></image>

    Oxygen Author displays the images in the article in the WYSIWYG view.

    From there, it's just a matter of transforming the DITA to HTML and publishing the HTML.

    We recently started automating how we manage images using the S3 API. We use a Python library called Boto 3, which gives you access to the S3 API. For example, uploading an image file with Boto looks like this:

    local_image_path = '/support/images/image1.png'

s3 = boto3.resource('s3')
bucket = s3.Bucket('zen-marketing-documentation')
bucket.upload_file(local_image_path, Key='docs/en/image1.png', 
  ExtraArgs={'ACL': 'public-read'})

    For more info, see the following resources:

    1
  • Ann Jensen
    Comment actions Permalink

    Thanks Charles,

    I have registered with Amazon AWS and am using a trial S3 service account. How do you manage authorization to your images in S3?

    Mine are not showing in Oxygen because of lack of authorization (403 error).

    Thanks again,

    Ann

    0
  • Charles Nadeau
    • Edited
    Comment actions Permalink

    We use a preference in Cyberduck to automatically set the correct permissions when we upload images:

    1. In Cyberduck, select Cyberduck > Preferences from the menu.
    2. Click the Transfers icon, then the Permissions tab.
    3. In the Uploads section, select Change Permissions, then select To these permissions (for Files).
    4. Set the following permissions:
      1. Owner: Read | Write
      2. Group: Read
      3. Others: Read
    5. Close the dialog box to save the changes.

    You can also change the permissions of the files already on S3:

    1. In Cyberduck, select one or more images, right-click, and select Info > Permissions.
    2. Click the gear icon in the lower left and select Everyone.
    3. Make sure READ is selected in the Permission column of the  "Everyone" row.

    Thanks.

     

    -1
  • Toru Takahashi
    Comment actions Permalink

    Interesting!

    Zendesk Team doesn't use Guide Editor internally?

     

    0
  • Charles Nadeau
    • Edited
    Comment actions Permalink

    Hi Toru,

    Most teams at Zendesk (Advocacy, HR, IT, Facilities, etc) have internal Help Centers and use the Guide editor to write content. As mentioned in the article above, the DITA process the Docs team uses for public-facing docs has a steep learning curve and isn't for everybody. Professional tech writers are generally familiar with it.

    Thanks.

     

    0
  • Toru Takahashi
    Comment actions Permalink

    Thank you!

    I hope Zendesk Guide focuses on the Doc team's use-case since public documentation can be maintained by the Doc team. Zendesk Guide is too poor to help the internal team yet.

    I like Zendesk. I hope Zendesk Guide would help you and us to write an article and maintain it without any alternative solutions.

    0
  • Moshe Armel
    Comment actions Permalink

    This is a fascinating and extremely helpful article. Our company's documentation is DITA-based, and are now looking to move from PDF documentation. I would like to know, which DITA repository system to you use? We currently use DITAToo. 

    0
  • William Kellett
    Comment actions Permalink

    My company is looking at migrating a bunch of DITA-based HTML to a Zendesk Guide. I read this article and was able to use the batch-publish tool successfully for a few topics that I had already created in Guide. However, we'd like to be able to use the tool to create (as opposed to update) articles in bulk from HTML. The readme.md file mentions mods that need to happen to the tool to create articles. Can you elaborate on what mods need to be done?

    Thanks!

    0
  • Charles Nadeau
    Comment actions Permalink

    Hi William,

    You have to use the Create Article endpoint and specify more properties for each article, such as the article's initial author and section, as well as it access permissions. Here's a quick script that'll upload a collection of HTML files to HC:

    https://gist.github.com/chucknado/40ff923e6a2eef6ad529bf32cd12640f

     

     

    0
  • William Kellett
    Comment actions Permalink

    Hi, Chuck.

    Thanks for passing along the script. Finally getting around to playing with it.

    I'm getting a 404 error when I try to run it. I know it's parsing the files correctly. I believe the API token is good. I know it could be many different things, but if you could point me in a likely direction for this 404 error, I'd be grateful.

    Cheers,

    Will

    0
  • Joseph May
    Comment actions Permalink

    Hi William-

    The 404 (Not found) indicates that a resource doesn't exist - it most likely hasn't been created yet, or is being referred to incorrectly. If you have a more explicit example of the error it might be possible to assist, but there are numerous possibilities.

    0

Please sign in to leave a comment.

Related articles

Related articles

Powered by Zendesk