Among my colleagues, the idea of documentation can be a bit of a joke. It’s one of those things that we know is beneficial, but it often ends up at the bottom of the priority list. As a software engineer, I get it – we’re notorious for finding ways to avoid documenting our work. However, decent documentation has saved my bacon more than once, so I’m a believer. I hope to convince you to integrate the practice of documentation into your work, too, by building a living, growing knowledge base for your organization.
At Clearistic, we work a lot with business process — we create web applications, mobile apps, and automations to help companies digitize or streamline their information flow. This work requires a deep understanding of how an organization works, and so this is usually where we begin. What we’ve found is that working to understand a process can be a minefield of tribal knowledge1, hidden fringe cases, and a general lack of clarity. To my surprise, we’ve found this to be true in most cases, no doubt a byproduct of the ever-increasing demands on our time.
The good news is that it’s easy to build an internal knowledge base that will evolve organically and which will relieve some of the issues that stem from complex or poorly-understood processes. Even if you don’t intend to do a deep-dive and streamline what you do and how you do it, there are a number of ways in which having a solid base of documentation will help.
Why Document?
Accelerate Onboarding
We typically bring on additional staff when the team’s work exceeds its capacity — that is, when we’re overloaded. That’s a tough time to train our eager new colleagues on the intricacies of our systems and processes. Imagine having an up-to-date knowledge base that explains the what, why, and how of the job. Not only will our new team members be productive more quickly, they’re likely to avoid some “rookie mistakes” as well.
Coincidentally, onboarding is a great time to test (and expand!) your documentation. You have a unique opportunity to obtain feedback from a motivated, untarnished source. Use that feedback to make sure your knowledge base includes critical information, is easy to navigate and is presented clearly.
Avoid Errors
Any time a repetitive task requires you to think, you run the risk of introducing errors. That is especially true in a distraction-rich workplace, where a phone call or a notification ding may cause you to lose your place. If you have a procedure that is intricate or delicate, build a comprehensive checklist. If you can, use a tool that supports literal checkboxes (OneNote is a go-to of mine). That way, if you are taken away from your desk, you’ll know exactly where you were when you return.
We’re always looking for opportunities to automate complex workflows, but sometimes that’s not practical. The nice thing about having a checklist is that, if you decide to automate a process in the future, it’s going to be much easier to do because you have the recipe.
Increase Supportability
Every once in a while, I prefer to not be working. With good documentation, my team can support me by taking care of certain tasks when I’m not around (and vice versa). An effective knowledge base enables team work and makes it easier for staff to support each other.
For documentation to be successful, it has to work when the author is not available to answer questions. Any time the knowledge base is actually used is a great opportunity to identify and fill in missing information. This is one reason we recommend using a technology that allows your team to enrich the documents collaboratively, over time.
Improve
As you document your work — whether to speed onboarding, reduce manual errors, or enable better team work — you may notice some odd things. If a task contains inefficiencies, you may be able to streamline it. If it’s highly repetitive, you may be able to automate it. Sometimes these opportunities aren’t obvious until you think deeply about your process, which is another benefit of taking the time to document.
How to Get Started
To me, the term “knowledge base” feels heavy, like some arcane Encyclopedia Britannica of your organization’s processes, policies, and procedures. It doesn’t have to be that way. There are many great tools available today to build your knowledge base, some of which I describe below. Whatever tool you choose, consider these guidelines to help your documentation effort flourish:
- It should be accessible, editable, and searchable. A good search makes it easier for staff to find and use the information they need. Editability turns your knowledge base into a living system that continuously improves.
- Don’t worry about perfection, or “it’s OK to start small”. Get something out there, even if it’s sparse, to allow your colleagues to give you feedback about what would help them. They may even begin contributing themselves.
- Use a system that allows you to refine over time. This is closely related to “editability” above, but it’s critical to use a system that reduces or eliminates friction when it comes to editing. If you have to log in with some arbitrary credentials (and reset your password, because you only use the system twice a year), people may bounce rather than take the time to contribute.
- Keep the tool open while you work. This is the key to making the work less painful. If you are able to flesh out your notes as you do the work, it requires very little thought to add context and detail to your documentation. Combined with “don’t worry about perfection”, you can create useful documentation without needing to schedule separate “documentation time”.
Tools
Here are some of the tools that we have used to build out our knowledge bases over the years.
Microsoft OneNote
If you are one of the more than 1 million organizations using Office365, you already have access to Microsoft’s collaborative note taking software, OneNote. While there are more sophisticated tools for this task, there are several reasons it’s a great place to start:
- Included with Office365
- Minimal setup
- Available everywhere (desktop, web, mobile)
- Supports collaborative editing
- Simple but effective organization (notebooks/sections/pages)
- Fast, simple search
If you’re not in the Microsoft universe, Evernote is a similar tool with a business plan to facilitate collaboration.
Microsoft SharePoint
If OneNote doesn’t give you enough control over the navigation and presentation of your docs, SharePoint (also included with Office365) may be a fit. It requires more setup and can become pretty complex if you let it, but it enables you to build a rich and evolving knowledge base.
- Included with Office365
- Rich content tools (styling, media, layouts)
- Fine-grained access control
- Share files and news content as well as documentation
- Workflow automation tools that you can grow into
Atlassian Confluence
Whereas OneNote is designed around note taking and SharePoint is more of a general information repository, Atlassian’s Confluence is purpose-built to share information within your organization.
- Templates help create a consistent look and feel for your documentation
- Collaborative editing includes real-time editing, comments, and notifications
- Deep integration with Jira ticket/task management system
MediaWiki
MediaWiki (the software that powers Wikipedia) is different than the options above because it’s not a SaaS (subscription) production. In fact, it’s a free and open-source solution that you’d have to host yourself. It’s also the oldest tool here (released in 2002!) and probably the least user-friendly. So why do I suggest it?
Years ago, during my time at WineAccess, I introduced a wiki running MediaWiki that quickly became an essential (dare I say beloved?) documentation repository for our business. It even outlasted my time there. While there’s a wealth of new, user-friendly options available today, MediaWiki could just as easily be a fit for your organization, too.
Keep in mind: The success of your documentation effort lies less in the tooling, and more in the commitment of your coworkers and staff to grow your knowledge base.
Side note: If there’s a Microsoft flavor to this list, it’s because we spend a lot of time with Microsoft technologies. We know that there are as many systems out there as there are creative ways to use them. We’d love to hear your recommendations so we can expand our list.
- Tribal knowledge is any unwritten information that is not commonly known by others within a company. What is Tribal Knowledge and how to capture it before it’s too late | Tettra