How product docs are produced at Zendesk

Have more questions? Submit a request

12 Comments

  • 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
    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
    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.

Powered by Zendesk