Featured image by Mitya Ivanov via Unsplash
This post is for Day 10 of Mercari Advent Calendar 2023, brought to you by @rey from the Mercari Knowledge Management team.
In this post, Rey discusses how a specific knowledge management tool may not matter as much as how you use the tool as a company; as well as the high-level relationship between search, navigation, and content discovery.
"Have you ever come across other software that aims to fulfill the same role, but works better overall?"
A few months back, the knowledge management team had provided coworkers with a quick rundown of the basics of Confluence, one the knowledge management tools we use at Mercari.(Why these types of training or open doors are important, we will explore a little more closely later.) After the session, security engineer and fellow Mercarian Viktor Ferter approached me with a follow-up question.
I had a kind of off-topic question, if you have time…
I see a lot of companies defaulting to the Atlassian suite for information management and tracking… Have you ever come across other software that aims to fulfill the same role, but works better overall?
I also feel like the biggest problem with these is a lack of a “bird’s eye view”. They are pretty easy to navigate within one team’s space but my job is usually across many teams in the org, and it’s very difficult to find the correct page without help from the team itself. Searching by something like “recently active,” “most viewed,” or “most linked to” would be pretty useful if Confluence could do that?
Basically, some of the most central aspects of these questions amounts to: (1) what’s the best tool to manage knowledge, and (2) within such a tool, what’s the best way to find knowledge?
It’s a pretty safe bet many readers have felt this way. How can we know more at work, and do so better and faster? Knowledge is, after all, power. And because empowering our software development (or in whichever industry you are engaged) improves our market performance, this search for a knowledge management silver bullet is a worthwhile quest.
So, Rey, master of knowledge, tech writer extraordinaire, pray tell us: What is the meaning to knowledge management life?
“Could it be better? It can. But, can it be worse? Yes.”
500 years ago, before Confluence or Google Docs existed, Saint François de Sales avait dit : «Fleuris, là où Dieu t’a planté». Translated, this reads, “Blossom, there where God planted you.” Efforts have the best chance of succeeding if they embrace the context whence they came. In other words, speaking on a case-by-case basis, you should always try to use the closest-to-native tool. The language “THIS SIDE UP” is best published directly on the package that must stay right-side up – not (merely) on the company site’s documentation section. Readme’s are better documented and updated in the source code repo, not on a Confluence page, nor should the readme merely link to such a page. A Confluence page that collects the links to the most important repos and presents them with short accompanying descriptions is a useful extension, but an extension nevertheless.
Again, as a first step, sticking closest to native will prove most effective. One might think, “Well, we use Slack all day, what about Slack notes?” … No. There are clearly limited tools, and their utility would be equally constrained. As a note-keeping tool, Slack notes might work. As a directory for team-related content, probably less so. Similar to the idea behind the serenity prayer, just because you can do something, doesn’t mean you should. Using a sports car to tow a boat is an easy way to damage both, and using tools because they’re built-in or “the way things have been done” (think: saving links to email chains to adding sheets to already massive spreadsheets) is an easy way to damage the quality of knowledge retained and the experience of the reader accessing it.
In this way, we return again to the question, “Well, then, so what is the best tool – generally speaking?” Well, generally speaking, if you were to run an internet search on enterprise knowledge base tools and pick the one that best matches your use case, pre-existing tooling, and budget, you would be mostly fine. As John Jurasek, the classiest food critic on YouTube puts it, “Could it be better? It can. But, can it be worse? Yes.” You have to embrace what you’ve got as a company. “Embrace” here means to centralize as an organization on actually using and maintaining the preferred solution, and providing training, awareness, and guidelines to help members contribute and feel comfortable and confident doing so. If a potential author has uncertainty or anxiety around “I’m not sure I know what to do,” even just one ounce of that discomfort is enough to get them to go rogue and spin up a new knowledge base or, worse, output nothing at all.
But, even in the internal training we use, we stipulate clearly: don’t embrace your tooling too much. Don’t get carried away with customizing macros or Myspace-ifying templates or layouts. Again, yes, use some of these features, at least the basic ones, and feel comfortable using them, but that’s it. The finer and more intricate the involvement becomes, (1) the more it becomes fragile (likely to break) and sticky (hard to migrate away from), and, more importantly, (2) the less time you spend on the actual content. Focus on substance, not form.
Finally, if your company is using Confluence, but you think Notion is better, or your team is using Jupyter Books, but you swear by Obsidian, consider the truth behind the adage about grass and it being greener on the other side of the fence. We spend all day on our lawn, in our garden. We know all the dead patches that need reseeding, and all the spots with outbreaks of indigenous weeds. Looking at our neighbors lawn in the distance, all we see is an emerald field of green. Oh! Would that we could detach from our ego and realize that our neighbor feels the same way about us!
It might actually be the case that you may prefer a solution because you are more familiar, not necessarily because it is better. In fact, it is unlikely that any solution entirely solves the fundamental challenges of technical documentation or knowledge management, because I’m not convinced those challenges are not entirely solvable. There are better and worse ways to deal with issues, and this comes down to matters of strategy, technique, and organizational rules, not so much the tool at hand, but at the end of the day you will still have to deal with the intrinsic issues.
“You’re not that guy, pal, trust me.”
One of those intrinsic knowledge management issues is content discovery. Finding stuff. With everyone in agreement about contributing to your organization’s knowledge base, you’re on your way to addressing the first issue, but what about the search, and what about the navigation? Search and navigation are related, but distinct topics.
Search is just plain never good. This is the bane of our times. When Google first came out, it certainly did blow AskJeeves out of the water, and it was a magical time for PageRanked search, indeed. These days, “curation” and motivations behind black box algorithmic manipulation threaten to cast us back to a state of bumbling ignorance about the digital world around us. That’s all to say, don’t rely too heavily on it: search is not that guy, pal.
Interestingly enough, AI, or A-Lie as some have taken to calling the more gimmicky solutions, does offer some hope in the case of knowledge management strictly within an organization. One of the most notable issues with (generative) AI is that it is based on empirical, and perhaps legally questionably obtained, source data. Whether or not that data is actually true is alarmingly ignored in chatbot responses. That is, depending on the input data, a query of “How do I make fresh orange juice?” could just as confidently be answered with, “Sure thing! First, take 12 medium-to-large size lemons…” However, when the input data is limited to all, and only, text which has been produced by internal employees, the likelihood of useful data, to say nothing of relevance, can increase significantly. So, to the issue of search, it does seem that an answer, at least for the next step, lies in technologies like LLMs.
As for navigation, there is more hope. One of the most effective techniques we can use to improve the navigation of our documents is to bake it into the text: navigation should be contextual and interlinked. It’s been about 20 years since we’ve had a proper web and it seems the idea of “hypertext,” specifically “hyper links,” is still slow on the uptake. One of the worst things you could do is write a 800 word page about your team’s tool and how to use it, and have no links whatsoever on the page. Or, if you operate in more of a business capacity, to write a 3-page proposal that references in text other company projects or history, but you do not take the time as an author to track down those resources and link to them in the document. That is a large part of the essence and value of technical writing: 1 person spends an extra 10 minutes expressing a point more clearly so that 100 other people won’t have to.
On a closing note to hyperlinked navigation, consider the tourism industry. A traveler should go see La Tour Eiffel, or مجمع أهرامات الجيزة, or the Empire State Building. But you don’t then go to France to pick up the tower, or to Egypt to uproot the Pyramids, or New York to grab the skyscraper, and then bring them all back to your country. You leave them where they are (and so we return on our journey back to Saint de Sales). Any focus on explicit, tree-like “navigation” should ensure that it is secondary to the quality of the content itself, especially with respect to hyperlinking, and with clear ownership and gentle reminders for maintenance.
“Write as much as you can carry”
With respect to search, or navigation, or even tooling, say, in the case of migrating, everything is easier to find or handle – and more likely to be true, if there is less volume, and if more people are involved in maintaining those resources (NB: Not in administering, just maintaining). Regardless of your tool or your page tree, maintain constant vigilance ensuring the resources in your knowledge base are clear, complete, concise, and consistent.
Ten Tips to Improve Your Technical Writing, the article I published for last year’s Advent series, opens with the first tip “Try to say it in less.” I kept this open-ended because it’s turtles all the way down: less words, less images, less steps, less pages, less documents: less. In a knowledge base, the same applies. But, I warn you: don’t reduce volume by gatekeeping before the fact with numerous, complicated, or strict governance. That just encourages little rebellions.
In Mercari’s Knowledge Management team, we like the phrase “sensible governance.” You reduce after the fact, in a 改善 kaizen spirit of continuous improvement, constantly manicuring your organization’s garden of knowledge. Have “docs days” to ensure ownership or archive outdated pages, or note that both of these frequently accompany turnover, so put processes in place to improve knowledge transfer. Run analytics on documents to help identify what seems useful, what needs help, and what needs to go. Not updated in 631 days? Adios.
A tech writer at Google (whose name I cannot find in my notes, but I’ll update this article once I come across it again) said, “Write as much as you can carry.” I agree with this 95%. But, I would say write more, since it won’t all work out. Docs and drafts, ideas and proposals, trackers and templates – most of the time, we don’t end up using it, or not in the way we intended. So, let it be published; publish it as it comes to you, just remember to remember it. You can always snip to cut roses, but you cannot snap to grow them.
Happy Holidays and Happy New Year
The Japanese word 粘り強く is defined as “tenacious; persevering; persistent; stubborn; steadfast.” It’s partly pronounced “nebari” and coincidentally sounds like the English “Never” (give up). Never give up! Though the search for a KM silver bullet may seem daunting, you must be dauntless in your commitment to providing your organization and your customers with excellence in documentation.
Thank you for sharing your time to trace my meandering thoughts. I’d like to close with a quote from my article last year:
Over the holiday and year-end season, I hope you find time to relax, enjoy good company, and perhaps think a little about writing. Better documentation makes the world better. I envy the delight of your readers as they get the answers they need and expand their knowledge with the great content that I know you can write. As they say in Mercari, Go Bold!
Tomorrow’s article, for the 11th day of Mercari Advent Calendar will be by @ayman from the Architect team. Please look forward to it!
