Executive Summary
Your docs don’t work. They are one of the few tools to make your team more productive; if anything, they often slow things down. This blog will go into why and how to fix it–making your team more productive along the way.
The Problem
Tell me if you’ve heard this one. You’ve got a new employee, and they ask, “So how do we foo the bar around here?” You’ve had a bad day, so you get a little snippy, “It’s in the docs, go find it.”
The new person fails to find the answer and sheepishly asks you once again how to foo the bar, but also lets you know they spent all day searching the docs. Frustrated, you share your screen and type in “foo” and “bar” in the search to show how easy it is. And…
Nothing comes up.
Well, the top results are all unrelated anyway–two meeting minutes from last year and some policy about email. The rest are all happy hour invites that someone put in Confluence.
Embarrassed in front of the new person, you start trying to piece together what little you know of Confluence’s smarter search. Is it file: to find specific files in the title?
The new person chimes in and helps you along–“Yeah, I had to learn all that today to try and find the doc you mentioned.”
Together you’re both unable to find the doc. The doc you wrote on how to foo the bar. You start just looking in your personal space and history. Finally, you find it, buried a hundred results deep, in some space you’d forgotten about, on some project that got canceled. And of course, you didn’t call it the bar back then; you called it the baz, so it wasn’t showing up.
Search Does Not Work
We entered the age of search not with Google Search but with Gmail. After all, Gmail extolled us all to “search, don’t sort.” And indeed, Gmail’s search was better than most email searches at the time.
Google’s internet search worked so well because it had the insight that links are valuable tidbits of information on a site’s reliability. One shouldn’t just look at the data on the page (the content and keywords) but also the metadata. Who’s linking to whom?
Before Google, we obviously had search. But we also had web rings and other web indexes. Whether companies or private individuals, a lot of work to build these web links on purpose was something Google’s internet search could utilize. After that, regular linking was enough to keep Google humming, but it had a large corpus of well-indexed pages.
Email, too, had a lot of metadata. It had dates, senders, and the rest. Your email response rates could help Gmail determine who was essential and guess what you might be seeking.
Fast forward to today. We have high standards for search. We expect to find what we’re looking for in the top three results, if not the top result. Confluence and similar tools, though constantly underdeliver. Why?
It’s the metadata. There is none. Most of the time, you might search Confluence; you want topics from your projects. You’re not necessarily interested in who wrote the page or when. Moreover, no one’s gone through and annotated pages to link them to each other. Confluence is mostly just a big document store, and we fall back on just parsing keywords.
Are we better at looking at keywords than 20 years ago? Slightly. But not much. It’s a hard problem. There are tons of hooks to add the metadata: page ratings and thumbs up/down features, the ability to add links, etc.; but that requires your team to use those features actively. If they aren’t, your docs are stuck inside a monolith.
Duplication
Search doesn’t solve the problem of duplicated efforts. If you are reading docs and you’re patient, a search may help you. If you’re writing docs, you probably click “new page” faster than you search to see what’s there.
This makes it super easy to duplicate documentation, leaving a trail of outdated and contradictory pages that all claim to be the source on how to foo the bar.
A Rose By Any Other Name
Often we don’t want keywords; we want topics. Being able to pull concepts and topics out of a bunch of documents is still a relatively “Hard Problem™.” So most off-the-shelf tools get you keyword search.
You might search for agile processes in your documentation and miss out on everything lean. You might search for peer review checklists and miss out on all the CI/CD documentation based on those checklists.
So much expertise nowadays is “knowing what to Google.” Google is a good search engine. “Knowing what to search for in Confluence” is more challenging since the search engine doesn’t have as much. Often it’s so hard; it’s just easier to ask the same question in Slack and get your answer immediately.
Once Burned Twice Shy
Someone only has to interact with the docs once or twice, not find what they’re looking for, and turn to Slack before they stop even trying to check the docs. If the docs are deemed uninformative by the office Zeitgeist, they won’t get used. You need your docs to reliably give the correct answer for people to use them.
Simply yelling at people for not checking the docs isn’t helpful. The docs aren’t helpful. By checking Slack, people are doing what intuitively feels most productive. Obviously, they don’t pay any of the cost of interrupting others, but that’s not why they do it. They do it because Slack gets them the correct answer and the docs don’t. Don’t yell at a dog not to eat your steak when your steak is delicious. Make the dog food more delicious.
Swiss Cheese Documentation
By using search as our fundamental API for our documentation, we don’t have any idea what’s missing. No overarching scheme can drive senior developers or managers to identify what’s commonly in lore and what’s actually documented.
Because huge chunks of process and policy are missing from these document stores, it makes them–again–less reliable. Since they’re less reliable, people rely on them less.
What If You Don’t Know What You’re Looking For?
Docs serve two primary purposes–training/onboarding and reference. In the first case, people often don’t know what to search for, so the search bar is useless. They don’t know enough of the office jargon to try enough different terms to come up with anything useful.
In the case of reference, if you’re anything like me, you either have your favorite doc bookmarked or just picked it out of your browser’s history. Alternatively, you may know the exact title, in which case, search becomes a glorified command line.
The Fix
The fix is, obviously, to organize your documentation. But how? We know we can’t rely on search as the primary means of interacting with docs. Indeed, no one’s saying turn search off. However, we’ll have to rely on more old-fashioned methods if we don’t have all the metadata needed for a good search engine to work (and our tool comes with a decent search engine).
This blog is going to introduce you to a few concepts. It can serve as an entry point to understand the broad outline of how your documentation is stored. It should have a dose-response effect. In other words, perhaps you can’t adopt everything (indeed, any change should be incremental and iterative); but anything that seems to fit what you’re looking for could be adopted by itself and still provide value.
Let’s dive into the most challenging part for everyone–document organization.
Organization
By the end of this section, you should have some ideas of various organization schemes you can apply to your documentation.
This solves many of the issues with search. By providing an organizational hierarchy, you discover what’s missing (because you have giant holes). A new person has a guided tour they can use to explore your docs without knowing what to search. Duplicated effort vanishes because if someone wants to add a new doc, they’ll see similar docs when they open the parent folder.
I’m not going to talk about an organizational scheme that can be used in every business. Instead, I will talk about meta schemes you can use to build a scheme for your business.
There are three main ways to organize documents: hierarchy, links, and tagging. As we mentioned above, we’ll have to rely on our old-fashioned methods, which means we need to rely far more on hierarchy than the rest of the world. In other words, we’ve got to relearn how to sort, not search.
Hierarchy
While this blog is titled how to organize your Confluence, it is meant to apply to nearly everything. This includes SharePoint as well as personal notes in Evernote or Obsidian.
We’re going to rely on whatever the folder metaphor in your documentation system is, and we’re going to use that as our new main API in our docs rather than search.
Folders model single inheritance thus, a document can only exist in one folder path. This folder hierarchy feature solves the swiss cheese and duplication problem. If you have an idea for a doc, you should have one path scheme that virtually everyone else in the company will utilize. Since you share the path scheme, you’ll quickly run into duplicates.
This is not unlike how a hash key works. We’re going to have a lot of buckets–our folders. We need one way to map any document to the same bucket and the entire staff to use that same scheme. We’ll propose combining two popular folder schemes: PARA and Johnny Decimal.
Deploy your PARA chute
At the highest level, we’re going to practice PARA. There’s much better documentation on the web on this system, and I’ve linked it above. So we’ll just briefly overview.
The highest level split in your documentation will break into four categories:
Projects
Projects are a series of tasks linked to a goal with a deadline. They are things you are actively working on. In an engineering organization, projects are features or groups of features in active work and stuff on the product roadmap.
If you use the Three Seashells system, projects will most closely align with your first seashell.
Areas
Areas are a sphere of activity with a standard to be maintained over time. These most closely correspond to functional or skill areas inside an organization. They are operations rather than projects.
Be careful to avoid strictly departmental schemes. In other words, if you have an “Accounting” area in your docs, it should cover how the business handles accounting issues rather than the accounting department.
For instance, accounting for capitalization of software R&D is–at least to me–an accounting concern, so that process should live in the accounting area. The accounting department isn’t a gatekeeper of what does or doesn’t get to go in the accounting area in the documentation.
Remember, people need to be able to navigate this high-level hierarchy like breadcrumbs to find what they’re looking for. Moreover, people should routinely trust areas outside of their own. If you are just using areas to “split up” where teams look for answers, you will get duplication as the accounting team will keep their notes on capitalization sequestered. In contrast, the project management team controls their own separate notes on capitalization. Without anyone linking between them, they will diverge.
Remember, one bucket for any topic.
If you use the Three Seashells system, areas will most closely align with your third seashell and guild.
Resources
Resources are a topic or theme of ongoing interest. They’re a bit weaker than areas where you should not have any business interests currently tied to resources. Most often, resources represent third-party resources. After all, if the business needs to actively maintain them, they should be tied to a project or area.
Resources may also begin merely as an idea that later turns into a project or area should the company decide to prioritize it. You can think of resources as primarily third-party docs that provide a bootstrap for where projects and areas come to life.
Resources, like areas, would primarily correspond to the third seashell.
Archive
The archive is for inactive items from the other three categories. If resources are where nascent projects or areas get born, the archive is where things go to die.
Of course, you can resurrect things from the archive.
One significant benefit of archiving finished projects is to make it easy for people to see what is in active work. Of course, if you keep JIRA up to date, this is easy too; the two schemes should correspond.
Next week we’ll layer another hierarchy on top of PARA, the Johnny Decimal system. We’ll also talk about the main links you want to focus on: the map of content. Stay tuned!
We’re on a mission to make jobs suck less, one software management tip at a time. We need your help!
Do you want to stay up to date on the latest management tips to help your team stay productive?
Click “Subscribe to the Soapbox” below for more!
.png)