How product docs are produced at Zendesk

Return to top


  • Charles Nadeau
    Zendesk Documentation Team

    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:

    <topic id="topic_h2z_wkk_w5" props="360022365413">

     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.



  • Valery Topilin


    I took a different approach, probably more complex:

    • I read dita hierarchy and compare it with the hierarchy in ZD eq. chapter-section-section-article
    • If I find an element in dita that doesn't exist in ZD then I create it and store the article ID & static link in the index object
    • when I get all the article links in the index - I do the second run and update all the cross references in the html code and reupload the hml code back to ZD

    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

  • Arno (EMEA Partner)

    Valery Topilin,

    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"?

    • A guess removing would be challenging, as articles might be related to sections, and could be done later manually on Zendesk side. They would not be visible to readers anyhow, if there is no documentation inside.

    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.

Powered by Zendesk