Help Center: Reusable contentPlanejada
We're working on providing both per-page help content for our app, but we also want to be able to provide workflow-based documentation. To that end, I'm surprised that the Help Center doesn't allow for any reusable content.
What I'm requesting is similar to the "include" or "transclude" syntax in wikis - there's a pretty good Atlassian doc page about what I'm asking about: https://confluence.atlassian.com/display/DOC/Excerpt+Macro This same feature is available in FrameMaker as "insets", and they're really important for working with highly structured documentation.
In a single-source environment, you mark a section of text from Page A as reusable, and basically set a URL that can be called to invoke the part you've marked for re-use. When you add a reference to that content in Page B, it displays the Page A content (usually) wrapped in the Page B content.
So for example I have a Help Center topic about what to do if you lose your card. There are a couple of other situations when you'd do exactly the same thing as if you'd lost your card, so I want to mark that procedure as reusable, and include it in the help center topics for those other situations. This way if, for example, the "freeze my card" help phone number included in that process changes, I only have to update it in one place, and not go hunting across the entire help center for any reference to that number.
I'm very happy to announce that we have opened a sign-up for Content Blocks EAP.
With this new feature, you’ll be able to capture things like common troubleshooting steps, rules and regulations, disclaimers, etc. as a reusable block, and then insert into multiple articles and across multiple help centers.
Documentation for content blocks is posted in the EAP discussion topic.
If you'd like to join you follow below link:
+1 for basic DITA capabilities.
Our software uses specific terms and phrases that occasionally change. When our Product Management department states we now refer to "Resume Parser" as "Resume Processor," it would be great if that tagged value could be edited in one place to affect the 259 instances of the term "Resume Parser."
Hey all -
Please make sure you've used the voting buttons on the original post to add your +1. Does anyone else have examples of how you would use this functionality or why you need it?
How we'd employ content reuse:
Using a string of text to insert a URL into an article. For example, let's say we have five articles that link to https://some-website.com/common-resource.
With content reuse, that URL could be referenced with something like a shortcode:
We then drop the shortcode into all five articles. Guide parses the shortcode and then displays the URL in all five articles.
Using a string of text to substitute for a definition. Let's say we have five articles that all include a short paragraph describing our product, Foobar. With content reuse, we drop in the shortcode [foobar-definition] into the article bodies. Guide would display an identical definition in each article body.
Using a string of text to substitute for an ordered list. Let's say we have five articles that all include these steps:
1. Update the foo.
2. Select the bar.
3. Save your changes.
With content reuse, we can reference that ordered list with a shortcode: [foo-the-bar-procedure]. So anytime we drop that shortcode in an article, the ordered list generates automatically.
Now the why:
Without content reuse, we have to manually update those five articles whenever a URL, definition, or procedure changes. And with articles spanning multiple categories or sections, we have to hope that running a search on Zendesk tells us all the places where we need to update certain content.
With content reuse, all you have to do is update one piece of content and the changes are deployed across multiple articles. See https://en.wikipedia.org/wiki/Single_source_of_truth.
- Using a string of text to insert a URL into an article. For example, let's say we have five articles that link to https://some-website.com/common-resource.
this would be great to have natively within ZD, but as a secondary option does anyone know of content management tools that could be used to create/manage KB content and then uses the ZD API to push the content to Guide?
I have been asking the same questions recently and have come across the following information
Hope this helps,
I'm currently trialing a cloud-based CCMS that integrates with ZenDesk Guide that could be a viable solution for some on this thread.
- Uses topic-based authoring
- Enables topic re-use
- Based on DocBook framework (but also integrates with Oxygen XML Author/Editor for those who prefer DITA)
I've published a few articles to our ZD sandbox and it was very straightforward, though I'll have to do some editing of our ZD theme and the Paligo CSS file to maintain the styles we want in our articles.
It looks like this might be a great solution for teams that don't have the time/resources to learn Python and manually leverage the ZD API. Paligo handles all of that for you and frees up the documentation team to focus on the content and strategy. I am giving myself a crash course on structured authoring right now (a huge topic, really) but this experience has been really eye-opening.
I am wondering if you have developed a way to integrate DITA content and Oxygen template design into Zendesk. Above you state that you use a DITA author (Oxygen?) to create your content and then convert to html and then push to the Knowledge Base? That seems a rather inefficient way to create content.
Are you looking at a way where we could use oxygen to create the content and not have to convert then push?
Also, when will one be able to create subsections within sections, and other ways to more cleanly display your KB topics? I have not seen anything about when this may, if ever, be available. I would like to be able to subdivide sections and have the subsections collapsible as I can when using Oxygen.
Hi Jenn -
More flexibility with categories and sections are tentatively planned for development later this year. Timelines may change and it is not guaranteed, but we do have it on the roadmap.
+1 for basic DITA capabilities.
I am also interested in your https://paligo.net/ experience Sarah Holdgrafer Its been a few weeks how is it going?
Is there any intention of putting DITA on the Guide roadmap in the next 18 months?
Hey Rebecca -
I'll check with the product managers and see if that's something they're discussing.
The Paligo trial has been super interesting and a great learning experience (I basically got a crash course in structured and topic-based authoring in the last month and a half, which has completely changed my perspective on how my company has been doing things - shout out to the Write the Docs community for chatting with me and sending me tons of great content).
The rep I've been working with (Steve) and the support people who answered my questions have all been incredibly responsive and also quite knowledgeable about how to manage the ZenDesk integration effectively. It's also clear they are really passionate about their platform and its benefits.
We decided to get a license for my team and we are also bringing the Paligo trainer down to train my team on advanced features (like versioning and localization), best practices, and strategies. Since all of our content is currently unstructured, the trainer will also be workshopping our content directly with us to ensure we can hit the ground running.
The platform itself is super intuitive, as is the publishing workflow. I'm really looking forward to developing our new strategy, and already have a ton of ideas that go well beyond just our knowledge base that would be logistically very difficult without such a platform.
I've shown it to our marketing dept with some of my ideas about how we can use it for various types of user documentation (specifically for onboarding), so they're intrigued as well but don't have the bandwidth to handle it right now. Meaning, I'm basically the company guinea pig :-) I think in a few months I can come to them with some deliverables, blow their mind, and then train them all on it as well. Is it weird that I'm so excited about this? ;-)
In general, yes we're looking at re-useable content and there's a few different use cases around that I'll try to outline below and give a few insights into where it might fit into our plan
- Publishing a single article to multiple sections or Help Centers - I've said this in a few other places as well but this is part of a larger work stream and we plan to have an EAP of this functionality available in Q1 2019
- Article templates - This is about being able to create an article from a base template and the author can fill in the details. We currently have some functionality around this using our Knowledge Capture applications. We are doing deeper research here to understand more about his and flesh out how it will work. No timeline yet on feature availability
- Re-use of portion of an article in multiple articles - We currently have some support in macros and themes for Dynamic Content. We are looking at ways to up-level this into truly re-useable excerpts kind of like Atlassian. No timeline yet on feature availability.
- DITA Support - As mentioned in a few places in this thread, there are a number of DITA based tools like Oxygen and Paligo. These are great and complex tools for documentation authoring. A few of these have already built integrations to Zendesk using our APIs or could be extended to integrate with Zendesk via the API. We haven't yet settled on any plans to investigate this further.
Also @Sarah, awesome to see people nerd out about this stuff :)
@Ryan, thanks -- Dynamic Content in article text would be huge!
Agree with Johathan's comment on Dynamic Content being huge. It would make changing a product or company name soooo much easier.
@nicole @ryan - any update vis-a-vis timetable to get ZD to work with re-usable content?
Any progress on the Dynamic Content? It would be a huge plus to be able to re-use content.
We are doing research around various customer needs related to how they might user variables (sometimes called placeholders) in Guide Content. Specifically we'd like to hear more about how you and your organisation would use features like: Frequently used names, contextual information, placeholders and formatted snippets, inline images, etc.
If you're interested in this research and would like to share your opinion, please fill out this form.
Any update this?
Hi Alejandro -
I know the product team is continuing to work on some functionality and an EAP is expected in the near future. They will provide an update here when there is something of substance to share.
Thank you for responding.
Is it possible for you to add that as an official response?
Sometimes, it is hard to find a Zendesk response in all of the comments on a post.
We'll mark the product manager's comment as the official response when they make one.
Any progress on this? For me, the ideal would use a Git repository as the single source of truth. Standard content management systems (CMS) such as Hugo, Jekyll, Gatsby, etc. already include this feature.
If we could import pages from Git repositories, processed by the CMS of our choice, into a Zendesk article, that'd be best.
In a past job, the organization that I worked for had to move away from Zendesk because of the lack of this feature. I'm wondering if I should recommend the same for the organization that I work for now.
Por favor, entrar para comentar.