Zendesk is now hosting customer-facing documentation. The documentation will still be developed in Confluence, but then must be synced with Zendesk. In an attempt to make syncing the documentation between Confluence and Zendesk easier, a plugin has been installed to Confluence that will automatically sync docs when they are changed.
Before following these instructions, make sure that the document you are working on belongs in the customer-facing Zendesk repository.
If you are not sure, please ping Nichola Moore.
How to use the Confluence to Zendesk plugin
The way the Confluence to Zendesk plugin works is that you force a sync once, and after that it happens automatically each time the Confluence doc is published.
To Initiate a Sync the First Time
When you have finished editing a document in Confluence, click Publish, as usual.
On the display page click one of the two options, both visible in the image below:
The two options are to click the icon circled above, or click … > Zendesk Sync. Both options do the same thing.
A pop-up window will appear when you initiate a sync for the first time:
Select a destination to sync to from the drop-down menu on the pop-up.
Click the Start Synchronization button on the drop-down.
Remember, you only have to manually initiate this process the first time you sync as subsequent syncs are automatic.
How to Change the Sync Destination
When you first sync a page you choose the destination. Subsequent syncs will go to that destination. If you want to change the destination:
Edit your doc Confluence and click Publish. The pop-up will appear, telling you that the sync is happening.
Click Stop Synchronizing.
This will disconnect the Confluence document from the Zendesk document.
To sync to a new destination, follow the instructions in To Initiate a Sync the First Time.
In some cases, the sync produces a usable document in Zendesk from the outset. There is, however, some formatting that Zendesk handles really badly, and has to be updated manually.
This means that when you have finished editing a doc in Confluence, you will have to go to Zendesk to check the formatting and update it if necessary.
The Zendesk editor handles the formatting of the tables but does not show any borders which makes the tables look strange. To fix this, edit the document in Zendesk and follow these instructions:
Click on the table
Click on the Table dropdown
Click on Table properties
Type 1 into the Border field. Click OK.
The table will now have borders.
You will have to do this with each table in the document.
Currently only the Standard Setup doc has iframes to handle jsFiddle callouts. The Zendesk editor does not deal with iframes, so all you get is no iframe at all in view mode, and a box in edit mode with which you can do nothing.
To remove the iframe box:
Click the Source Code icon circled in the image below:
Edit the source code. Scroll down to the section showing the iframe. There does not appear to be a search facility in the source code editor.
Remove the section that looks like this:
<p> <iframe width="100%" height="550" frameborder="1" align="middle" sandbox="allow-forms allow-modals allow-orientation-lock allow-pointer-lock allow-popups allow-popups-to-escape-sandbox allow-presentation allow-same-origin allow-scripts allow-top-navigation-by-user-activation"> <p> </p> </iframe> </p>
The details may be different but the <iframe …> and </iframe> tags will be there. Remember that there may be more than one iframe.
Check the wording around the iframe to make sure it still makes sense
Move the Code Samples from the iframe
In the case of the Standard Setup doc, you will have to copy the code samples from the iframes in Confluence and paste them into a code block as follows:
Copy the code from the Standard Setup doc
Click the code block icon in the Zendesk editor toolbar:
Paste the code into the empty code block, which will present as a grey rectangle:
Internal and External Links
Many of our documents link out to other documents for explanations. The Confluence to Zendesk sync does not update the links to Zendesk docs, which means that document links must be updated manually.
Update the Links
Click on the link you want to update, then click on the link icon:
You will see the Insert/edit link pop-up.
For external links, search for the required document in the Help Center article tab. You may have to refer to the Confluence doc for the correct link. You cannot link to particular headings in external documents in Zendesk like you can in Confluence, so you may just have to link to the correct document. You can link to sections in the same doc. See #Internal-Links .
Be aware that the document to be linked to must exist in the Zendesk Help Center. This should not be a problem because external-facing documents only refer to external-facing documents. They should all be in the Zendesk Help Center.
Select the correct article, check the Text on Link, and then click Link.
To create links to other sections in the same document, click Heading in the Insert/edit link pop-up.
Select the correct heading and make sure that the Text on Link is correct. Click Link to complete the link.