We can hold the knowledge of countless generations literally in the palm of our hand. It’s an amazing thing, but the downside is that a fair bit of that ‘knowledge’ isn’t worth the pixels that display it.
Bad info is frustrating enough in everyday life. But at work, the quality of your information can mean the difference between success and failure. And that goes for you, your colleagues, and your whole organization.
K15t was founded on the principle that teams should be able to share great know-how freely, easily, and flexibly. We think internal knowledge is the lifeblood of an organization, and that external knowledge is a powerful enabler of customer success.
Hear why knowledge sharing is so important from our marketplace partners, Deviniti, codefortynine, K15t and Kolekti:
So, what stands in the way of you having a great know-how practice?
It could be as simple as changing some bad habits which stem from unhelpful ideas or legacy mindset. There are myths to be busted for sure – we’ll put the spotlight on some biggies below.
Though this is all about people first and foremost, Confluence is a great tool to help you on your way. So let’s roll up our sleeves, dive into four big blockers, and learn how to overcome them.
Challenge: ‘Everyone Already Knows This’
Team members who are authoring know-how need to presume readers have some common knowledge to avoid boiling the ocean when they describe a process. But it’s all too easy to make assumptions about what others already know, which may or may not be true. No set of instructions can include everything, so the challenge is to find where to draw the line.
For example: We’ve all followed an internal guide to set up a software tool, like your organization’s password manager. The instructions may seem simple enough, but can fail because they have no exception handling guidance (such as if your browser version isn’t current enough to use the password manager plugin). A new employee might not have heard the tip regarding browser updates, and they become blocked by something which is common knowledge amongst the existing team.
How to overcome this:
- Tailor your content to the intended audience and explicitly state your assumptions at the beginning of the article. In general, err on the side of over-informing versus assuming background knowledge. You can use the `/expand` macro in Confluence to hide background information in sections to avoid interrupting the flow of the page.
- Give authors ways to find out where users struggle, such as the ability for users to comment inline or at the bottom of a page. The native comment functionality in Confluence is great for this. Learn more best practices around comments on the K15t YouTube channel.
- Break out of the ‘doomed to repeat’ mindset by actively encouraging internal teams to improve documentation directly on-the-fly. This assumes a certain degree of trust, but direct edit access can be a massive help since gaps can be closed while they’re fresh in mind.
- If your content will be informing readers with very different backgrounds or use cases, consider writing two versions of the article. Alternatively, you could use Variants for Scroll Documents, and conditional content macros to have one source page and generate multiple variants based on user type. Learn how Emplifi uses this approach to deliver their documentation to multiple types of readers to great success.
Challenge: ‘I Don’t Need to Write This Down Now’
This one is about that ‘flow state’ when we’re hard at work on a task, and focused intently on reaching the next milestone. Problems arise, and as we work to solve them it feels natural to press on to the next challenge in the sprint to the finish line.
The mindset is ‘I’ll capture that info later on, once I’ve gotten past this next bit . . .’ But when we get interrupted, or something else consumes our focus, it’s all too easy to neglect going back to capture the knowledge.
For example: A customer success team member is working to deliver a summary report of user feedback from a recent feature release. There is a new feedback tool in place, and the team member has had to do some manual data ingestion from the tool to a custom spreadsheet in order to crunch the numbers needed for their report. In the late stages of the task, a bout of the flu hits our hapless team member, forcing them to take the rest of the week to recover. This leaves the team without the report or the knowledge to hop in and produce it quickly themselves.
How to overcome this:
- Work on projects directly within your knowledge platform ‘single source of truth’, so that you can capture info right where others would search. Again we’ll recommend Confluence for its simplicity and flexibility – including chart, table, graph, and database functions. Learn more about charts and other page elements here. We even stay in Confluence and use its presentation mode for reviews with teams or groups!
- As you work, think of what you’d need to know to repeat the process and take note of any resources you consult. If you’re using Jira to track your work, you can embed the issues you’re working on into a Confluence page and leave space below each to capture notes. Once you find a format that works well, create a Confluence template and share with others to facilitate this way of working throughout your organization.
- Capture the journey as well as the result. Plan your work in smaller chunks and make documentation efforts part of the ‘definition of done’ for each step. This gives you a chance to pause, evaluate, and capture knowledge before moving on to the next step, and provides a more granular overview of the progress being made on a project.
Challenge: ‘Nobody Cares’ or ‘Nobody Needs to Know’
Similar to the above myth, it’s easy to think that your problems are unique, and that no one else will ever need to know the details of what you’re doing or the challenges you face. Especially at a larger organization, it’s difficult to see how a challenge or solution in your business area could affect another, especially if they serve very different needs.
Yet this assumption is dangerous, because it often leads to duplicated efforts, which, at best, are a waste of time, and at worst result in significant costs and incompatible solutions.
For example: You work in HR and have been looking at ways to track onboarding for each new employee. Your HRIS tool doesn’t do this, so you build a spreadsheet to enter the information manually.
At lunch, you talk with a coworker who mentions how they’ve been helping the Legal team integrate a new tool to manage contract documents. Then later in the day, the Customer Success team publishes a blog post detailing how their new onboarding tool makes it super easy to track the progress of each new customer.
After a few conversations, you realize that either of the tools could have been a solution to your problem, and the company has now purchased two different (and incompatible) tools to do essentially the same thing.
How to overcome this:
- Document and share your challenges and blockers, not just your solutions. Use Confluence to clearly define the context and scope of the problem, and share widely for visibility.
- Encourage cross-functional collaboration. When similar challenges arise in different parts of the organization, it’s very likely a common solution can be found. At K15t, we have an organizational structure called ‘Circles’ where members from widely different parts of our organization meet and share knowledge about a common focus area such as design or user experience.
- Rescue information from DMs. Asking and answering questions directly in Confluence is the preferred method, but sometimes these things come up in conversation on Slack/Microsoft Teams or even at an actual watercooler! After conversations like these, be sure to update the Confluence page so that everyone can benefit from them.
Challenge: ‘This Isn’t Ready Yet’
Sharing work early feels uncomfortable. But when team members keep it hidden, rabbit holes, fruitless diversions, straying from the original brief, and wasted time are far more likely to occur.
Opportunities for important course correction also get missed when work stays hidden for too long, as well as critical alignment with those who have expertise to share or might be duplicating efforts. Being aware of critical inflection points during your work will help you get the feedback you need when it’s most valuable.
Even something as simple as adding styling or other polish to your drafts can end up being a waste of time when you realize later that they’re unusable due to an unforeseen change.
For example: You’re documenting a new feature that involves a complicated set of interrelated configuration options. The developer preview version you’re using is a confusing experience, but you slog through on your own and chart out how they all work together. It’s still a lot of information, so you then write out step by step instructions for each case.
Unfortunately, when you proudly reveal the documentation to the team, they tell you about the different regional versions of the app. Your work isn’t technically incorrect, but in practice no one would have access to all the options at the same time. The development team in this example fell victim to the ‘Everybody Knows This Already’ myth, and by not sharing early, you missed out on some key context that would have saved you a lot of work.
How to overcome this:
- Make sure your teams have the psychological safety to share work before it’s ‘ready’. When you foster a culture of collaboration and transparency by default, early feedback and iteration rounds will become business as usual. Agile documentation practices can really help – learn more about them here.
- Keep pages public and unrestricted whenever possible. This provides discoverability for others who may be working on similar things, or have expertise or critical context to share.
- Encourage all to make a minimal time investment and create a rough outline or sketch to discuss during a kick-off. Even if something winds up on the cutting room floor, it’s infinitely better to have this and other actionable feedback from the get-go than after many hours have been spent.
Conclusion
Now that you know more about these four documentation myths, and have some techniques to overcome them, we hope you’ll find plenty of opportunities to put them into action. You may even be doing some of these already yourself, without even knowing it!
At K15t, we truly believe that enabling quick and painless know-how sharing, and treating every challenge as an opportunity to improve your knowledge base, are the foundations of success. And they foster a happier, healthier working environment for you and your customers alike.
K15t help teams share their knowledge freely, simply, and effectively to better educate and enable their users.
Turn your Confluence pages into beautiful help centers and user documentation with rich output functionality and full control over styling – then publish content to the web.
Try Scroll Viewport to create beautiful help centers and web pages from Confluence.
Check out these helpful Marketplace apps to resource teams and boost productivity:
Extension for Jira Service Management – enhance your ITSM customer experience to delight your customers with this app from Deviniti
Deep Clone for Jira – Start saving time with powerful cloning tools to clone epics, bulk clone and copy project templates with this app from codefortynine
Scroll Viewport – Create intuitive help centers and beautiful web pages in Confluence with scroll apps from K15t
Content Formatting Macros – Help your teams work more effectively with this essential Confluence macro toolkit from Kolekti