I’ve recently discovered that I can decrease the time to find relevant documentation with a single action: link related documents together. This may seem obvious, so let me elaborate.
Conway’s law in documentation
When the company grows, some structure is applied to it. It could mean multiple departments for example engineering, marketing, customer support. If the company uses a knowledge management tool, the documentation structure may likely reflect the company structure. We may say that the documentation, similar to software, is susceptible to Conway’s Law.
Any organization that designs a system (defined broadly) will produce a design whose structure is a copy of the organization’s communication structure. — Melvin Conway
For example, It could mean that each department has its own Space in Confluence. We may be looking for information differently, depending on where we look for it. If we’re in our department’s space, we may be familiar with the structure, but not necessarily with others’ structure.
Different ways of finding the documents
As I described in another article we may find documents differently depending on our purpose.
- We may be browsing through the pages to understand the problem space – stumblers
- Or we may be trying to solve a particular problem – seekers
It’s very likely that if we browse through documents, we do it in our space.
And if we search for specific terms or words we may not find what we’re looking for because the other department may call the same things differently, or the naming has changed over time. It also depends on the tool we use and the search engine used under the hood.
Avoiding dead ends
There’s one more angle to look at the problem. If you find nothing useful, you have the motivation to keep searching. But if you find a document that seems relevant, but doesn’t have enough information you must just stop there. You may think that there IS documentation. It’s just poor. It may block you from searching other spaces. If the document has a link it’s a natural path to the other pieces of knowledge.
A real story
Here’s a real story that I’ve experienced recently:
One of the company’s products offers additional accounts. Customer support reported a problem that the additional account didn’t renew together with the main account. As an engineer, I was asked to investigate that.
Additional accounts are activated by sending an activation code using a lifecycle marketing tool mainly managed by the marketing team. The workflow in the tool however was implemented by another engineer. I didn’t know how the workflow is configured so I browsed through the Confluence pages in the Engineering space (a stumbler), however, I couldn’t find any documentation. I tried to search but I couldn’t come up with good search phrases (a seeker). Therefore I started figuring things out, and creating new documentation while doing it.
When I finally understood the flow and created a page I received a response from the engineer who originally created the workflow, who shared some Confluence pages with me. One of them was in the Marketing space and the other was in the Customer Support space. Together they covered almost everything that I described in the new documentation.
I decided to delete almost the whole content of my document to avoid repetition, leave parts only relevant to engineers, and link the pages from other spaces. I also linked back my page on the pages in other spaces
But even if my document was supposed to be empty I still would create it, just to link other pages from the Engineering space. Only to serve the “stumblers” who find the page and want to learn more.
Why not tags?
Confluence (but also other tools) enables an additional level of structuring – tags. We could then auto-generate pages that list pages with a relevant tag. While this is very powerful and flexible, it also requires creating a system and understanding how it works. And managing such a system becomes even more complex if we want to do it across departments. Just linking a related page is much, much simpler.
