Organizing Your Documentation

As a kind of addendum to my post about the rules of documentation, I thought I’d share a bit more about our documentation approach and structure at Variance. As a new company, it’s fun to get a chance to start from scratch and try some new things while also building on what’s worked in the past.

I’ve broken the post down into a few sections:

1. The Knowledge Stack
2. Organizing Your Documentation
3. Contextual Knowledge
4. Wrap Up

The Knowledge Stack

Before diving into the content, let’s talk about what a documentation stack could/should look like. As I see it, you need a few core components:

• Knowledge Management: This is what people typically think of when they think of documentation. It’s a place to store, and more importantly organize, the key documentation of a company. We choose Notion for this job, but Confluence and Slite are also good. To me the key thing to look for in a Knowledge Management system is how easy they make it to a) find things (both search and discovery) and b) update content. 
• Collaborative Document Editing: While Knowledge Management is great at storage, it’s hard to measure up to the sort of rich collaborative editing experience you get in Google Docs or Microsoft Word (online). Most documents, certainly ones that require collaboration, should start in one of these tools and move to Knowledge Management once it's completed. (Points here to Dropbox Paper as well, which never really took off, but built a nice collaborative editing environment—particularly if you wanted to include code blocks, which Docs is terrible at.)
• Contextual Knowledge System: We obviously have a pretty strong bias here, but to me the missing piece of this stack is all about how you bring documentation closer to the actual work being done day-in-and-day-out. For that to work you’ve got to be able to access knowledge in the flow of work. For instance, if you’re using a development system like Jira or Asana, but have all your documentation about how sprints work in Confluence or Notion, then you have a big disconnect between what you want people to know and where you want them to know it. For developers, this job is a lot easier because their documentation is mixed right in with their code, but for the rest of us, we need a different answer.

Organizing Your Documentation

Once you’ve made some choices about those systems it’s time to start thinking about organizing your documentation. Here I’m going to focus on how to do it in your Knowledge Management system since that’s the system that is most reliant on employees being able to discover and search for documentation.

To my mind there are a few key ways to aid discovery in a Knowledge Management system:

• Front Page
• Organizing Structure
• Internal Links (I’m not going to dive into this one, but it’s about connecting documentation with links—hopefully self-explanatory)

Front Page

A front page is mostly an orienteering exercise: an attempt to help people understand where they are and where they might need to go. Our Front Page highlights both our organizing structure (which I’ll talk about next) and also the key areas an employee may want to explore.

There are also two more pages embedded in this one: Organizing Notion and Using Notion. The latter talks about a lot of what I wrote above. Specifically, what Notion is and isn’t good for.

Good:

• Archiving documents and outside writing
• Organizing ideas
• Saving inspiration or research screenshots
• Spreadsheets/tables that require content (good rule of thumb: don’t use Google Sheets if you need to save text that’s more than a sentence or two long)

Not good:

• Collaborating on documents
• Building budgets or other spreadsheets that require calculations

Organizing Structure

Of everything in this doc about docs, this is probably going to be the most foreign. It’s still experimental for us, but so far I like it. As you might have noticed in the screenshot above we use a non-traditional organizing structure. It’s one I learned from Tiago Forte whose work on Building a Second Brain I’ve been a fan of on a personal level for a long time. Forte recommends a framework he calls PARA for keeping your personal Evernote organized:

For the purposes of company documentation, here’s how I think about the different categories:

• Projects: Generally belong to an area and have an end date.
• Areas: These are things that are specific to your company, like departments, and also things like brand and culture which are unique to your organization.
• Resources: Think of these more as topics of interest. They’re not specific to your company, but they’re something you keep up on. Could be your industry (we have one for SaaS) or the ways you work (we also have one for remote working).
• Archive: This is for everything that’s inactive. As a rule it’s good to over-archive to keep things clean. It’s not like you’re deleting anything.
  

Here’s how it all looks in the Notion sidebar:

Wrap Up

Knowledge, as they say, is power. But knowledge without context is often meaningless. Last year I was introduced to the idea of the “skills transfer gap” in a Harvard Business Review article about executive education. The gap is the one between where a skill is learned and where it is practiced, and can be the deciding factor on whether someone actually internalizes something. From the article:

One of the biggest complaints we hear about executive education is that the skills and capabilities developed don’t get applied on the job. This challenges the very foundation of executive education, but it is not surprising. Research by cognitive, educational, and applied psychologists dating back a century, along with more-recent work in the neuroscience of learning, reveals that the distance between where a skill is learned (the locus of acquisition) and where it is applied (the locus of application) greatly influences the probability that a student will put that skill into practice.

While they’re talking about executive education, it could just as easily be applied to the problems we face in documenting everyday practices and processes. The further the learning space is from the doing space, the harder it is to internalize and put into practice. Ultimately organizing your documentation is about finding ways to shrink this gap and make it easier to discover and use the knowledge stored in your documentation when you need it most.