How to Create a Seamless External and Internal Knowledge Base Experience
Creating a great documentation experience for your customers and team is tricky. Here's our insight into how to make it as simple as possible.
Creating a wonderful, seamless documentation experience can save your team time, money, and keep everyone in the loop. A bad documentation experience on the other hand can cause confusion, stale information, and extra unwanted admin work.
Splitting out your documentation seems like a solved problem.
You have external documentation for customers with a Knowledge Base. For internal documentation, you create a collaborative Wiki so everyone on your team can contribute. It seems like the obvious solution.
For a while, I thought that was the only way to do it too. If only it was that straightforward.
Over time I started to realize that it certainly wasn't that simple. Documentation can come in many forms and keeping it simple isn't that simple at all.
For example, you might have a special VIP program and you only want your VIP customers to access parts of your documentation. Or you have an executive team but you don't want anyone else to edit your meeting notes.
In this post, I'll explore the variety of strategies you can use to keep your external and internal documentation together. Having them split across different ecosystems might not work for your customers or your team.
Two buckets full: authoritative vs. collaborative documentation
I tend to speak to Taylor—my co-founder—in riddles. Fortunately, they're able to translate my nonsense. Unformed sentences turn into formed thoughts when filtered through Taylor's brain.
I remember thinking about all the confusing layers of documentation.
Sometimes people want everyone on their team to edit and contribute content, sometimes they want it to stay the way it is and teach the reader, and sometimes it's a hybrid of the two.
I started vocalizing my thoughts to Taylor and they started to decode what I was saying.
"So you're trying to work out whether people want to collaborate or not on documentation?" they said. "Sounds like that fits into two buckets then. Authoritative docs and collaborative docs".
Stealing these wise words, I think these two buckets define the ways people tend to split out their documentation.
Authoritative documentation: You're explaining the process of something to an audience or you're documenting something that happened in the past. Great for how-to guides, technical documentation, onboarding, and meeting notes.
Collaborative documentation: You're working together and coming up with something new. Great for generating product ideas and working through problems. This is usually inside a Wiki.
In this post, I'll only be talking about the former—authoritative documentation.
How do you create a seamless documentation experience across different types of readers? Your reader might be a customer with a special plan, a new team member looking to submit their paperwork, or an external company looking to help with your extra outsourced tasks.
Why seamless documentation helps teams move faster
The earliest evidence of documentation dates back to around 3400 BC on a clay tablet that listed the plowmen employed by the state and the assigned land used as payment.
"Those with good documentation could carry on as usual in the comfort of their own homes. The ones who didn't scrambled to write all the knowledge down somewhere".
Strangely not that far from what we use documentation for today like who's responsible for which department in the company. You could say it's a type of internal documentation.
Fast forward around 5,400 years and an event I'm sure you didn't miss made seamless documentation as important as ever—the pandemic.
The height of the pandemic in 2020 meant pretty much everyone was working remotely.
Those with good documentation could carry on as usual in the comfort of their own homes. The ones who don't scramble to write all the knowledge down somewhere.
A report by McKinsey in August 2020 explained that "Many organizations will need to rapidly reinvent processes that previously required physical documents, to become paperless".
Remote work was once a treat granted to executives who didn't fancy commuting through the lanes of traffic to get to the office, or to early adopters in startups who thought huddling in an office seemed a little pointless.
After the worst of the pandemic remote work has more of a platform. Granted, many large companies are backtracking on this idea and requiring their employees to slowly return to their desks. Despite this, workers in the US still prefer remote work when it comes to work-life balance according to Pew Research Center.
Seamless hybrid internal and external documentation allows remote workers to have all their authoritative information in one place, meaning less context and tab switching.
All documentation leads to your company hub
The great thing about an online-first team is that all your communication usually runs through one hub. This hub could be a Slack or Microsoft Teams workspace. It could be a Discord community or Telegram group chat.
Having your documentation plug into this hub helps you run a constant feed.
Not only does it help relay information as soon as something inside your documentation is triggered—like an article being published—it also helps remind your team it's still there to be used.
This hub will reduce the chance of your information going stale and your Knowledge Base fading away. If your authoritative external and internal documentation are connected to the same platform, your team won't have to log into separate accounts making the process a lot easier.
Whatever piece of software you've chosen as your hub, to avoid disruption and encourage customization I'd recommend setting up a dedicated area for these notifications.
If that's something like Slack, a channel named #docs to feed into will help to stop new article notifications popping up between discussions of how best to revive your drowned Monstera.
Plan your permission grouping
Like most things, planning comes in handy when you're thinking about something at this scale (I know, planning kinda sucks right?).
You want to avoid overcomplicating things. For example, if you're going to have a section for external and internal documentation, it's pretty simple to create a permission group just for your internal team.
Since we're a small team here at HelpDocs we deploy this strategy. We have a single Permission Group named "Team HelpDocs" and a category with subcategories inside named "Internal".
If you're a larger company with departments split out you'll want to create a wider selection of Permission Groups. There are a few ways of doing this:
Split by operational department
Your documentation could be split out by department.
Accounting will likely need completely different documentation to say, the engineering department. And the engineering department probably doesn't need to know the ins and outs of your accounting software.
Similarly, if you're in eCommerce your suppliers will need very different information from your marketing department.
This will depend heavily on your company operations and how your teams run internally. If you have a flat management structure maybe you'd like all your team members to have access to everything in case they need to hop in.
If you have a hierarchical management structure you might want "Managers", "Senior Managers", and "Executive" groups so you can provide various information that's only relevant to those people inside your organization.
Here's a quick example in case you'd like a starting point:
| Group name | Example documentation |
|---|---|
| Customer support | Ticket style guides, billing management processes, support scope |
| Marketing | Software processes, checklists/worksheets, co-marketing guidelines |
| Engineering | Development environment processes, pipeline guidance |
| Onboarding | General company information, setup guides, internal request forms |
| People Ops | Management guides, process documentation |
| Sales | Transcript templates, sales software processes |
| Executive | Company vision, board meeting templates |
| Partners | Co-marketing guidance, developer guidance, conference processes |
Having relevant information tucked away for each department will make it easier for everyone to navigate and get to the information they need.
Create tiers
Another option is to create your own tiering system which simplifies the system.
For example, you could have Tier 1 which is the executive team and people who work with them. Tier 3 would include the newest members of your team.
Tiers make it easier for large organizations to move quickly, allowing managers to assign Permission Groups solely on their current role at the company.
Here's an example of the tiers and type of documentation you could include for each:
| Group name | Example documentation |
|---|---|
| Tier 1 (Executive) | Process documentation, budget guidelines, internal company goals, funding information |
| Tier 2 (Management) | Management guidelines, process documentation, people ops targets |
| Tier 3 (Senior) | Process documentation, expensing guidelines, management guides |
| Tier 4 (Junior) | Process guidelines, onboarding documentation, how-to guides |
Hybrid department & tier system
Sometimes having them split out one way isn't enough.
Let's say the marketing department managers need to have specific documentation that the junior members don't need at all. An example of this could be the marketing budget information where junior members might not need to know how much you're spending on Adwords per month.
In a case like this you could create both systems like so:
| Group name | Example documentation |
|---|---|
| Marketing - Tier 1 | Budget guidelines, internal marketing goals, funding information |
| Marketing - Tier 2 | Marketing management guides, budget information |
| Marketing - Tier 3 | Style guides, marketing templates, |
For this system to make sense you'd be a large organization because it can get pretty complicated fast if you're not careful.
Embed external content into your articles
If you're like us, you use a variety of different online tools to help you run your accounting, marketing, engineering, and sales.
To keep your documentation relevant, you can embed information from these various tools into your articles. These are usually called—quite rightly—embeddables.
Let's take for example the editorial calendar. A staple in most marketing teams across the board. With all sorts of content needing to be posted and scheduled, an editorial calendar is changed at least weekly if not daily.
If you use a tool like Airtable, you can embed an editorial calendar inside your Marketing Overview article.
Another example is Sales. Let's say you can have an article named Sales process. This could include an embedded Salesforce Widget that shows the current status of your sales pipeline.
In both examples, embedding information from external sources keeps the article relevant which makes sure it doesn't go unseen and unloved.
Make logging-in easy
One of the reasons internal documentation gets abandoned is because it's tricky to log into. Passwords get lost, it's not front-of-mind, or the information is partly updated in a different place leaving the old content partially fresh and stale.
A simple way to stop this from happening is to integrate your internal login process. You might use OpenID or SAML single sign-on to get your team into your other internal tools.
Add this to your internal Knowledge Base and you're much more likely to encourage and increase the adoption of your internal docs.
You can also make it seamless for your partners or customers by cookie-ing them. This could be done manually or through something like JWT. People would only need to click a special (but secure) link and they'd have access to the restricted information they're looking for.
It's easy to assume people will just look at your internal documentation because you ask them to. The reality is a little different.
Keep everything authoritative in one place
Internal authoritative content has its place in the heart of an organization. Without it, company processes and information that you don't want to collaborate on would end up being overwritten and under-utilized.
By having your external and internal documentation in one place, you're making it a lot easier for your team to understand where your documentation lives.
In the end, it's about which approach is more intuitive for your team. Will your team expect to find internal content in the same place? Or is the content different enough from your public content that they would expect it to be separate?
Whichever approach to use, keeping your documentation easy to access and top-of-mind ensures it gets used and updated.