Tobias Davis

Designing better software systems.

Articles | Contact | Newsletter | RSS

Site logo image

Always be documenting

A company knowledge base–a set of documents where those in the company can create and update documents–is a strong indicator of good company health. Having one and regularly using it are different things, and in this blog post I’m going to talk about why you should have one and what makes it powerful.

Get a knowledge-base #

Do you have a process within your company that can’t be fully automated, like publishing a podcast, and sometimes you forget a particular step and it costs you time or makes you look bad?

Or have you ever connected several third-party services together? If you’re like most people, you probably read through documentation, clicking different buttons, trying different configurations, and eventually you have everything set up just right but you aren’t real sure how you got there?

What you need is a company knowledge-base. A source of documents, where anyone in the company can add documents and update them. (I’ll talk about why the “anyone” is important later in this post.)

I use Notion pretty heavily, and if you use the Atlassian tools you’ll probably already be familiar with Confluence, but almost any “wiki” tool should work.

The two primary purposes of a knowledge-base are to share and document knowledge.

Document your knowledge #

This is a very functional business decision, and is measurably effective at helping achieve business growth, because good documentation makes it obvious what things can be automated, and good documentation prevents mistakes.

What is “good” documentation? The answer is pretty obvious: documentation that people actually use and maintain is good. It doesnt matter how long or detailed it is, it’s not “good” documentation if nobody bothers to use it!

Not too many companies have podcasts, but imagine that you did. Think of all the things you might need to do to really create a great podcast:

That’s four poorly-documented steps, and publishing a podcast has many more steps. When you start your podcast most of those steps won’t be automated, they’ll need a human to do them.

Humans are inconsistent and error prone, but if we have carefully prepared checklists to follow, we are less likely to forget things. If you’re in a hurry you might forget to upload a cover-image, but if you have a checklist you’re unlikely to forget.

A good document for publishing this hypothetical podcast would be a checklist template that the person actually doing the publishing would copy and work through each time they do the work.

Documenting is automation #

When a process is documented, you can begin to see where you can improve it. Drop repetitive steps. Notice dependencies that cause things to fall in critical status more frequently. Notice dependencies that can be removed. See where tooling can eliminate whole chunks of work.

In his excellent article “Manual Work is a Bug”, Thomas Limoncelli describes documentation as part of a process to automate everything:

The successful engineer realizes that the earlier he starts collaborating, the sooner others can contribute. Together they can create a culture of documentation that spreads throughout the team. Thus, every project is collaborative and has a “stone soup” feeling, as all are invited to bring their skills and insights. The more people who embody this culture, the more success it has.

You don’t need anything formal, you just need to start with baby steps. Next time you do a task that you’ve done many times, write down a simple checklist of everything you do. The time after that, try following the checklist, and update it to handle the things you forgot.

Each time you repeat this cycle, you’re turning the task into something that you can either fully automate or safely hand off to someone less experienced.

Documenting is a safety net #

Years ago, I was an intern at a now-defunct nuclear plant, and an event happened that has stuck with me ever since. The team I was on was working on a project that was taking a long time and costing a lot of money.

One day we all went to lunch together, climbing in to a single elevator at the same time. Nothing happened, but my boss pointed out that an elevator accident at that moment would kill off the team, costing the company hundreds of millions of dollars.

We didn’t all get on the same elevator after that, and the point has stuck with me: if a project is important, I shouldn’t be the only one who knows how it works. It’s not only the extreme of death, an employee should be able to go on vacation or quit due to family needs, and be confident their work will continue in their absence.

Documenting is an indicator #

Sharing knowledge creates a safety net for the company, but makes the employee’s position weaker.

It takes a lot of introspection, maturity, and trust for an employee to be able to say “I don’t want to be the critical link”. When they do, they are giving up a lot of control–if they aren’t critical they can be replaced, and that’s makes them vulnerable.

This is why I say that a well used knowledge-base is a strong indicator of company culture and health. A healthy company with a good culture will have a strong foundation of trust, which allows an employee to become vulnerable by giving up that control.

If employees aren’t documenting the things they do, even if the knowledge-base exists, this is almost always a failure on the part of management in developing a culture of trust.

Software requirements #

Hopefully I’ve given you a strong foundation for why your company needs a knowledge-base, but there are many different options, and each has pros and cons.

The following two points are what I consider to be the most critical. If your software meets these requirements it’s probably fine for the purposes of knowledge sharing.

Easy to add collaborators #

Have you ever tried to use a document that was woefully outdated? Many times this is because the person doing the work isn’t able to update the document or template. This goes against the whole purpose of a shared knowledge-base: the person doing the work will notice areas of improvement, or steps that are outdated, so they should have the power to update it.

Fostering a system of trust and knowledge-sharing requires that everyone in the team can create and edit. Many companies want to “talk the talk” and say that everyone is important, but if that’s true (and I believe it really is) than everyone should be able to document anything they think is important to be documented.

It may be necessary to partition knowledge between teams, but unless you are working with personal data or have HIPAA restrictions, it’s usually best to make the whole knowldedge-base accessible and editable by everyone in the company. Siloing information in teams is dangerous and costly to company performance and stability.

All changes are visible #

If you accidentally change something, you should be able to see what changed. If anyone changes something, everyone should know what it was that changed and who did it.

This isn’t necessarily about bad actors, although having changes visible helps with that. Things like accidental clicks, bad internet, and buggy software shouldn’t be a cause of stress–if someone accidentally makes a change, it should be visible so they can undo if needed.

The changes should also be visible to everyone, not just the one who changed it. Fostering a system of trust requires the humility to have your mistakes visible.

This post is more opinionated than normal, but that’s because cultivating an environment of shared knowledge and trust is so critical!

Companies who master it are many times more productive than those with toxic environments of knowledge-silos and distrust.

I’d love to hear your thoughts on how you’ve improved company culture by using a shared knowledge-base!

Your thoughts and feedback are always welcome! 🙇‍♂️