Embedding Help – Best Practices

Scroll Viewport provides a help center widget that you can use to embed your help center content directly within your own app.

On this page you’ll learn how to use the in-app help feature properly so your users can use your content conveniently right from your application or website.

To learn what the feature does and how it works, please check out Embed In-App Help .

Break up Long Articles With Page Inclusions

It may be the case that your help articles contain information related to more than one area in your app. If your user opens the in-app help, they probably want help for the specific area of the app, and not general information. You can achieve this by separating the content into separate pages in Confluence.

For example:

In our help center we have an article with the title "Get started" which describes the onboarding process which contains 5 onboarding steps.
In our UI the onboarding process is a step-by-step wizard. Steps 1-5.

Here is what we need to do in our help center first:

Create 5 new article pages, one for each onboarding step.
On your "Get Started" page, use Include Page macro to include the 5 articles.

Now we could already implement our in-app help feature for the 5 onboarding steps in the UI and match them with our 5 new articles.

Exclude Any Duplicated Content From the Help Center

When embedding articles in your app, we recommend to re-use the content you already have. That’s not always possible, especially if you’re trying to break up longer articles or want to keep content much more succinct than on the help center.

To avoid any unnecessary duplication of content, we recommend that you add an exclude label to the articles that are used exclusively for in-app help.

Adding scroll-help-center-exclude-page as a label to your Confluence page will exclude these articles from the navigation and search on your site. Those articles are still live and can be visited from the web, but the pages are hidden within the help center itself.

Make Sure That Embedded Links Remain Stable

For software that can’t be modified after it has been deployed, it’s especially important to ensure that the links you embed always direct to helpful content. Links can easily break, for example, when you move the content you link to to a different page or replace the page where your content lives with a new page.

The best way to ensure that links don’t break is to generate your links with context keys, instead of copying the URL that is shown in the browser.

Read more on Generate Stable Links (Context Keys) . Please note this feature requires our app Scroll Documents.

If you don’t have Scroll Documents and can’t use links with context keys, Viewport can help you recover broken links in other ways:

Customize URLs. If you move your content to a different page, you can try to mold the URL of the new page to match the URL of the embedded link. This might not always be possible, especially if the content source or page title is not the same anymore. Read more on Customize URL Segments
Redirects. If embedded links can’t be replicated, you can always set up redirects in Viewport. With redirects, the embedded link remains broken but redirects ensure that opening the link automatically directs users to a different page. This is especially helpful when you migrate to Viewport from other help tools. Read more on Literal Redirects .