I recently answered a question about organization tips in a forum with a description of our internal knowledge base built with WordPress. Since that forum is not public, I wanted to share it with others who are looking into building their own knowledge base with only small technical demands.
What’s a knowledge base?
Our internal knowledge base is the place where our team puts information for internal usage.
It is the kind of information you could define as “documentation”. It keeps our knowledge.
The principle: New team members get access and can learn everything about our organization and how to properly function in it.
That’s the vision. In reality, there is just too much to consume at once, a lot is irrelevant for everybody, and there is always something outdated, or missing, or not structured well.
Still, it goes a long way if we at least try to follow the main principle.
Our internal knowledge base is only the third place where we put information in.
Trello is not a knowledge base
Our daily tasks are handled in Trello. We keep information that is related to such tasks as “try a new plugin”, or “write a post about XYZ” in there.
We had a “documentation” list on every board to keep information about finished tasks. It is not a good place, though. One has to remember certain cards and information about shared topics is spread throughout different cards. Search in Trello isn’t great either.
Most important for us: it is not in our control. We are already too heavily relying on Trello for daily task management. What if – and that happened – Trello is down?
So we decided to keep information in a knowledge base solution that is simpler to extend and structure.
Keep as much as possible public
When something is about our Advanced Ads plugin, we try to keep as much as possible in the public manual.
That is natural for information like using the product.
It is not so common for many plugins to write about possible conflicts and how to resolve them. Except for Advanced Ads, I know that WP Rocket is doing a great job here.
We try to keep as little information as possible about debugging internal. Experienced users might find the answer themselves when they know about all the tools we use.
The same accounts for information about discounts or refunds. Though, there is little use for any client to know how we handle them technically in our store backend.
Some companies have developer handbooks, style, and communication guides publically available. I am not against that. We just don’t have them figured out yet.
Using WordPress for a knowledge base
We had a few demands on our internal knowledge base:
- simple text editor
- simple internal linking
- structuring content by teams or topics
- layout without too much distraction
- sidebar with the main structure
- simple upload of images
- table of content
By “simple” I mostly mean through an intuitive UI, not writing HTML or other markups.
If anyone reached out to me asking for a solution, I would instantly point towards WordPress.
But what did I do first? I installed a MediaWiki. If you tried that, then you know that all of the above is possible. But if you came from WordPress, “simple” is not a term I would use to describe the Wiki editor.
Finally, it dawned on us that I already know the solution. We installed a new WordPress instance on a subdomain and were able to start documenting right away.
The setup we use today is a bit more advanced. But not that much. Here is the basic technical setup:
- We secured the site from outside access with a simple “maintenance” plugin that asks everyone for access + an additional HTACCESS password
- Every team member has read access, most also unlimited write access
- We use Activity Log to see who made a particular change, in case something breaks, so that we can better educate users
- Easy Table of Content for content tables. We have them in the sidebar
- Syntax-highlighting Code Block to properly highlight code
- A custom theme with easy-to-read font settings and a sidebar for search and quicklinks
We still make backups manually but will have to implement automatic backups soon.
Thanks to only a few plugins we are using and WordPress updates rarely causing issues, maintenance of the knowledge base setup is fairly quick and easy.
The static homepage is a landing page linking to often needed posts or central topics like the team structure.
Some topics have dedicated landing pages, like support.
Categories and some custom taxonomies make sure we find posts by team or topic (e.g., dev, support, or refunds, accounting).
Advocating for the knowledge base
Thanks to WordPress, the technical setup of a knowledge base is simple. The real challenge is in keeping the content up to date.
Whenever we gathered information that might be relevant in the future, someone has to remember to put it into the knowledge base.
That shouldn’t be the role of a single person. The whole team needs to be involved.
Our experience shows that someone needs to nudge others at the beginning.
Over time, people will see the benefit, when they find the information they didn’t know existed or can go back to their own notes and save time on a task that suddenly came up again.
I am still the most active author in our knowledge base. Whenever I add or change something there, I post it in a dedicated “kb” channel in our company Slack for everyone to see. I khow, this also reminds them of the place they can leave information and look things up.