No matter which business you are in, chances are that there is a lot of information you want your customers or users to find.
That information is valuable for your clients to discover how to use your service and, as a result, reduce the number of incoming requests your customer service receives. It can also play an essential role in building your company's SEO strategy.
Many services on the market can help you quickly set up a public knowledge base, from Intercom, Help Scout, Zendesk to more specialized services.
This article covers from beginning to end how we, at Routine, decided to build a public knowledge base using Notion and Super.
The problems with existing knowledge management services are twofold.
Most companies maintain their internal information through a service that is different from the service they use to expose information to the public.
For example, a company could rely on Trello, Asana, or Atlassian for everything that relates to project management and Google Drive for managing internal information.
However, the public knowledge base would be set up using a different service, often siloed from the rest or coupled with customer support, which is often the case with Intercom.
The problem is that information must often be duplicated between those two knowledge bases (internal and public) as they serve different purposes.
For instance, the human resources department may maintain a list of open positions along with potential candidates in their internal system while those same positions would need to be exposed to the public for visitors to notice and potentially apply.
Another problem most companies run into (or maybe do not even know about) is that their public documentation quickly becomes outdated.
Take your pick: Mailchimp, Google, Front, etc. All of those established companies have public documentation that has become inconsistent: from documentation telling you to click a button that does not exist, to assets (images, videos, etc.) that are so old the user can't understand.
As a result, the user reads the documentation that showcases a product that has nothing to do with what the user uses.
Let's take a look at an example with Mailchimp's documentation on how to create automations:
Now, this is what the service looks like as of December 2021:
The documentation explicitly tells the user to look for Classic Automations as the second step, but this banner and link are nowhere to be found on the service.
Likewise, notice how the visuals for step 3 differ from what the service looks like.
It is not complicated to foresee the Mailchimp teams' difficulty maintaining that documentation since every release can invalidate all or parts of the public documentation that is already available.
At Routine, we decided to rely on Notion as much as possible early on. Let us go through an example to set up a public knowledge base through Notion.
To start with, create a page in Notion and share it publicly.
Remember to activate Search Engine Indexing if you want your public knowledge base to contribute to your SEO. Note that this functionality is not provided in Notion’s free plans.
You can now start structuring the information of your public knowledge base but also organizing visually.
For the sake of this example, we will create eight pages, each representing a topic, while the main page will act as a menu and will be organized in two columns.
As you build your public documentation, you will likely realize that some information is not ready for prime time yet.
Likewise, some info is only for your team to see and should never be accessible from the public, though living inside your public knowledge base.
For this example, let us say that page Sharing represents a functionality that is not ready yet.
We want to hide it from the public and continue working on it until it is complete.
You have to open the page in question, click on Share, and deactivate Share to web. A message will warn you that this page will be restricted from public view.
To quickly know which pages have been restricted, you can add an emoticon at the end of the page name, e.g., 🛑.
Sometimes, the information you want to hide from the public is not a page but a block of text, a section header, or else.
The issue is that Notion does not make it easy to manipulate a block’s sharing permissions.
Fortunately, Notion has been designed with the block as the core object, meaning that the blocks can be manipulated as pages.
As of December 2021, this is not very simple to accomplish in Notion. Hopefully, it will be straightforward by the time you read those lines, in which case the following will have become irrelevant 😂.
Let's create a call-out block in our Notion public page to warn our colleagues that this page and its sub-pages must be treated very carefully since it is shared with the public.
Then, click on the block’s handle and select Copy link to block. Open your browser and paste this link.
If you validate, you will see that it brings you to the page with the block highlighted.
To change this block’s properties (e.g., permissions), you will need to edit the link and remove the text between / and # (including the # character).
As an example, https://www.notion.so/Public-Documentation-a903cdf7273a41ddbc4cf0456645bd9b#3a2be7e401fd4c1da89d441a4f6b9b83 becomes https://www.notion.so/3a2be7e401fd4c1da89d441a4f6b9b83.
When entering this new URL in your browser, the block will appear as a regular page.
You can control the sharing permissions for this specific block from that point. Click Share and restrict the permissions by deactivating Share to web.
As a result, the public will not see this block while still visible and manipulable by your team.
As explained in the introduction, one of the problems with existing public documentation services is that information is sometimes duplicated between the internal knowledge base and the external documentation.
If this information does not live in the same system, it becomes tough to maintain over time.
With Notion, you can collaborate and maintain information with your team and decide to share some with the public.
Let’s assume we have internal information that relates to recruitment. We have a Positions database that lists all the available positions.
Every position has several useful properties: who is the manager in charge of hiring for that position, the department the recruit will work in, etc.
In addition, another database contains all the candidates. Every candidate entry references the position they applied for.
You might want to share publicly: (i) the list of open positions, (ii) without exposing all the properties such as who the manager is, and (iii) while keeping private the list of candidates that reference that database.
You would need to open the Jobs public page and create a linked database to reference the Positions database.
Next, adjust the default view (or create another one) to filter the information to display to the public, e.g., hiding the properties you believe are not necessary for the world to see.
The same can be accomplished to share a roadmap even though every roadmap item references another database of epics, for instance.
Likewise for changelogs which could be easily maintained internally while linking a database of product versions without the public being exposed to internal information.
At Routine, we use this technique extensively to easily share and maintain a lot of information: Roadmaps, Changelog, Jobs, Press, Integrations, etc.
Let us now look at the other major problem with existing public knowledge base services: the difficulty for teams to maintain documentation up to date over time.
Let us take an example by writing a company description on the Company page.
Later on, the team decides that it also wants to introduce the company on the Jobs page.
There are two ways to accomplish this:
The problem with the first approach is that the user is taken to another page, hence breaking the flow.
The second approach is very risky as the chances are that when someone from your team updates the Company page’s description, she will forget to apply the same modifications to the other pages, e.g., Jobs.
Notion’s synced blocks provide the best of both worlds by allowing you to re-use one or more blocks from one page to keep them in sync at all times.
As a result, if someone from your team were to modify the text, it will automatically reflect in the other pages.
Simply type /sync and press ENTER to create a synced block. Drag & drop the blocks you already have into the synced block. Then, copy the sync block and paste it anywhere, and those will be kept in sync.
This technique can ensure that information is written once and kept consistent across your internal knowledge base and public documentation.
This is particularly useful as marketing material and communication change over time.
The same mechanism can maintain other assets such as images and videos.
As described in the introduction, even large companies like Mailchimp fail at maintaining the public documentation consistent with the product developments.
As functionalities get developed, and user interfaces improve, the documentation must be updated to not only change the text describing the product but also replace the images and videos showcasing the product.
Notion’s synced blocks can once again be used to that effect.
First, let’s create an Assets page to store all of the product and marketing assets, from GIFs, logos, screenshots, etc.
For every asset, a synced block is created to ensure that they remain in sync when they get copied.
Now that the assets are all organized in one place, they can be re-used both internally and throughout the public documentation.
The Assets page must be shared publicly to display the assets in the public knowledge base.
Whenever the product changes, maintaining the assets up to date becomes simple.
Instead of browsing all the pages composing the public documentation to see if the information has become outdated, you need to browse the Assets page and update the assets that have been impacted by the product changes.
All the pages from the public documentation automatically get updated to display the new asset.
At Routine, we store all of our assets in a public page accessible here: assets.super.site.
Those assets are used throughout our public knowledge base to showcase how to use the product and the Brand Guidelines page, which journalists use to re-use the right colors, logos, etc.
Now that our public knowledge base is ready, you may want to give it a look and feel which matches your brand.
For this, we use Super.so, a service that turns Notion public pages into websites.
Once logged in, create a new site, enter a name and the URL of the Notion’s main public page.
You can also attach a custom domain name for your knowledge base to feel even more professional.
Click on Domains, and you will be able to change both the default domain Super assigned to your site and attach a custom domain.
Just follow the instructions to update your DNS server.
Super provides several useful functionalities.
Among them is the ability to add search functionality to your site and include a menu.
Open the Options section and activate Site Search to enable the search feature.
A menu can be added in the Theme section by activating Custom Navbar. You will then need to customize the items in the menu, the look, and feel, etc.
Other features include adding Google Analytics & Cloudflare, password-protecting pages, and many more. Check out Super.so’s website for more information.
Interestingly, a public knowledge base can play a critical role in increasing your site’s SEO, given the qualitative and quite specific content it hosts.
Super allows you to specify the SEO information: title, image, keywords, description, etc.
Just open Pages and click on the globe icon next to the page you want to configure the SEO information.
Fill out the information and repeat the process for every page of your knowledge base.
To push it a bit further, you can set icons for the pages of your site.
You could use emoticons as Notion natively supports, or you could go as far as designing your own set of icons to match your brand.
To apply an icon to a page, open the page in Notion. Then click Add Icon and select a new icon: emoticon, from a link or uploaded from your computer.
Below is the difference between the original version and the version customized with specific icons:
You can find sets of icons for free on platforms such as The Noun Project, flaticon, etc.
You may find that before setting up Super, the linked database views could be opened without any problem while they now lead to an error page that looks like this:
This is one of Super’s current limitations.
All the elements (pages, blocks, etc.) that you want to be displayed publicly must live in the hierarchy of the main page you provided Super when you set it up.
If in a page in your public knowledge base, you reference a page that is not part of the public knowledge base hierarchy, you will get this error. Even if the page referenced has been shared publicly, Super will not display it.
One of the ways to fix this is to move the main objects to the public knowledge base hierarchy and reference those objects from the rest of your internal knowledge base.
In the example below, the Positions database lived in the Human Resources hierarchy.
As a result, even though a visitor could see the list of positions, it was not possible to open the “position” item.
Switching to have the original database in the knowledge base and creating a linked database on the Human Resources page solves the problem.
Note that Super generates a static version of your website. Therefore, it can take several hours for Super to run and generate a new version.
You will not be able to check your modifications until then. One way to overcome this limitation is to check the website through Super’s browser.
Open Super and click Pages and navigate through the pages with a standard browser.
Instead of having two separate systems for managing internal and public information, using Notion with Super allows you to maintain a single information system.
It does not mean that it will be perfect and that you will not miss outdated information.
Still, it will be a lot easier for you to spot inconsistencies instead of managing two distinct documentation bases.
At Routine, we extensively rely on this technique to maintain our public knowledge base, which is available at http://base.routine.co.
And if you love Notion, you might enjoy Routine to supercharge Notion with time management, recurrent tasks, contact management, and more 😉.
