/
(In depth) Public Knowledge Base System

(In depth) Public Knowledge Base System

Owned by Brent Meriwether (Unlicensed)
Last updated: Oct 06, 2021
7 min read

This article contains the full knowledge transfer of how our Confluence + K15t knowledge base system works. If all you want is the quick introduction, please see (Quick Guide) Docs & contributing instead.

Overview

Our new Confluence-based Knowledge Base uses a combination of Confluence Spaces and a 3rd party plugin (Scroll Viewport by K15t) which renders these into Knowledge Base themed public facing URLs under our public site on scrollhelp.site.

It’s important to understand that our end-users / partners get links not to Confluence but to the rendered view that gets served up in our public-facing help site url (on scrollhelp.site). Confluence is the CMS, scrollhelp is the hosted output.

  • Changes by us get made in Confluence.

  • End-users see those changes after they are pushed live to our scrollhelp site.

We also have all of our knowledge base sources directly linked on the myDevices Docs site. If all you are looking for is a single URL you can hand out that contains all of our content sources, that’s where to go.

List of Knowledge Bases

Our public Knowledge Bases content is drive from Confluence Spaces and rendered into a public view via our iot-help scrollhelp site. Each Confluence Space that we choose to share out gets a separate Knowledge Base URL that can be handed out to our end-users.

Here is a list of the public Knowledge Base Spaces that we have:

Space Name

Purpose

Language

Status / click for URL

Space Name

Purpose

Language

Status / click for URL

Customer Help

In-App Help

English

LIVE

Partner Help

Partner & Console Help

English (no plans for localization)

LIVE

A Confluence Space will only appear to the public when it is added into our Scroll Viewport configuration. Thus the list above of LIVE sites is the complete list of publicly available Knowledge Base URLs that can be accessed by our partners/users.

Make changes in Article content

The following will help guide you on how to add or update content in our public facing knowledge bases.

Category Updates

Add, Edit Help Articles

Anyone is able to add or update help articles. We should all collaborate together to get this content in place.

  1. Open the appropriate Space in Confluence (see List of Confluence Spaces).

  2. Drill down in the list of Pages until you find the Category where your article will live.

    The display of Categories is the same when viewed in Confluence versus the public site.

     

  3. Open the article for creation or edit

    1. If you are editing an existing article, hover over it and select Edit (or you can do so after clicking on the page to view it).

       

    2. If you are creating a new article, just click on the + sign in the category.


      You can always drag & drop the article to somewhere else if you make a mistake in where you create your article.

  4. Use the WYSIWYG editor to create the article content.

    See below for some useful hints on article creation content using Confluence.

  5. When you have finished your changes use the Publish button. Your changes are saved as draft until then.

Confluence Article Tips

Here are some tips on creating / using Confluence for Help articles.

Most of these tips will be related to using the Insert to add a widget / control to help you with displaying content.

  • Use Heading 2 and lower by default. The K15t uses Heading 1 for display title display.
    See their Scroll Viewport Best Practices for working with their theme

  • YouTube videos can be embedded using the Widget insert.

  • Use the Children Display if you want your article to include a list of sub-pages appearing under it.

Update our Live Site

Confluence pages drive the content, but the K15t Scroll Viewport plugin is what renders our content to our live site.

Scroll Viewport takes whatever Spaces we manually set to include and when the content is generated it pushes those out as separate “apps” (separate Knowledge Bases), each of which can be access at the parent site or as sub-URLs that can be handed out.

Access Scroll Viewport

You can access the Scroll Viewport configuration in a couple of different ways - from the Apps option in Confluence or while viewing one of the pages.

 

Pushing Live

As noted earlier, changes to Pages in confluence aren’t visible to the public until our live site is updated.

When you access Scroll Viewport, it will show you which spaces have a list of pending changes.

Going live is done by:

  1. Use the Update Site button from Scroll Viewport to start the Generate process.

  2. The Generate process will package up all the Space content and spit out a Preview of the changes.

    This process will take several minutes.

  3. Once the Generate process is complete you will get a report and the ability to Preview your changes.

  4. If you are satisfied that everything looks good, you can use the Go Live button to push them public. This part is instantaneous.

Add support for a new Language

Currently K15t’s Scroll Viewport plugin does not support Localization within a single source. As a workaround, we have separate Spaces for each language.

See List of Knowledge Bases above for that list.

The process for adding support for a new Language is thus:

  1. Create a new Confluence Space.

    1. Give it a name such as “Customer Help (<Localized Language here>)”. This will help us to locate it easily in Confluence as well as to give it a nice display in the In-App help.

    2. When setting up the Space, you must a specific Key based on the language.
      It should be “IOTKB” followed by the 2-letter ISO standard for that language.
      e.g. IOTKBDE = German, IOTKBFR = French

  2. Localize the English content sources into your target language.

    1. You can either Copy the English source Pages into the new Space and have them manually update each article in their space, OR

    2. You can give out a read-only link to our English sources / package it up as an export / whatever works best and then they must replicate each Page into their space as they make progress.

    3. I would probably recommend Option B since the Copy process in Confluence seems rather dicey.

  3. When you are satisfied with the content you can add the Language to Scroll Viewport.

    1. Use Add new Content Source in the Scroll Viewport view.

       

    2. Point it at the Confluence Space that you set up for that language.

    3. You can then Generate a preview and push it Live once it’s good.

    4. Please also update our List of Knowledge Bases at the top of this article as well.

  4. The final step is to make it available in the Product. Currently this requires a new push of the PWA with a changed flag.

    1. Create a card for the Dev team to enable the Language + Language Flag for the chosen language in our dropdown.

    2. The dropdown assumes you will be using the 2-character ISO code for the language (e.g. iotkbde for German), but it probably wouldn’t hurt to link them to the full scroll help site URL just case.