By Nicholas Graziade on Writing docs, Tools from July 16, 2020
I have a nasty confession: I have had few chances to write creatively in the past several weeks. This isn't due to lack of inspiration or drive. This isn't because I have stumbled upon a dearth of topics that I can share. This isn't because I didn't want to put the pen to the page, so to say. No, this is simply because my mind has spent most of the month on overdrive.
Allow me to share some context. I have been working as a business analyst on a government contract since early this year. While I am no stranger to the legal and departmental complexities that I must navigate in this role, I think I may have actually overclocked my brain trying to sort out one topic. It isn't a difficult topic. The fundamental concepts are not overwhelming. However, the seemingly bottomless mess of rules seems, well, insurmountable. I feel like I have been hovering above my own body, seated at my desk, watching the madness consume me.
Days upon days gathering requirements…
Hours upon hours refining documents…
All my mental cylinders in motion…
Every synapse firing…
Every moment wishing the whole array of requirements would simply write themselves…
…and that's when it hit me – an awesome topic to share!
I've been privileged and have taught several classes on the basics of academic writing, and one of my favorite topics for younger learners is the research essay (I'll venture to guess that some of you are already experiencing some nasty flashbacks - I will try to be brief).
Academic essays are strange monsters. They coalesce information to communicate concepts, reveal common themes, prove points, share research, and myriad other ideas. But keep in mind that they take all manner of facts and data into one unit. Much of this information comes from predecessor scholarship. To that end, I've always stressed citing sources and making sure that you organize these sources along topic strings that help a reader move from one topic to the next. To show students an effective strategy, I'll grab a stack of index cards and share the following steps:
That's it! The essay writes itself!
We know that we can find a way to easily organize information for an essay. However, can we apply a similar process to our knowledge bases?
(I think you already know the answer!)
Let's imagine you've landed a great job as a knowledge manager with a new company, and they need you and your team to maintain their knowledge base, which already has hundreds of articles. But there's a catch - the articles lack any sort of unifying structure. The content is great, and you can already tell that the writing and the style are perfect for your clients. However, it's all buried in a rather plain subsection of the company website simply labeled "Help." No organization, no navigational scheme, nothing. Naturally, the company wants to bring this help text to the forefront of a new adoption effort that's beginning in six weeks. But you're a new user to their platform, and without some way to make sense of the clutter, you're already feeling like your first month and a half is your swan song...
...but if one student can use index cards to write an essay, one team can use index cards to organize a knowledge base.
After a few meetings with your team, you immediately get a sense for which topics relate to one another. Not a bad start, but because you are supporting an adoption effort, you go one step further. You've scheduled several meetings with people from around the organization: sales representatives, customer support agents, developers, and so on.
There are only a handful of staff in each meeting, no more than five or six, but they each perform the same task. You hand them each a stack of 50 index cards. Each card has one article title from your site, carefully curated by your team. The participant task: organize the index cards by topic. Some people make a few large stacks of cards while others divide them into two dozen smaller stacks. The developers see things slightly differently than the sales reps, who in turn see things slightly differently than the operations staff. Your team looks at all the strategies and how different roles categorize the same information. You ask questions, take notes about why certain topics seem to fit together, and after ten of these sessions, you're ready to act. You and your team look at all the common threads among the different groupings and ultimately find a way to organize the content in a way that unifies the content in a way that serves your audience.
That's it! The knowledge base organizes itself!
There's a two-fold lesson in this. The first is that some of the simplest techniques can provide the best insights around structure and organization. The second is that when you are stuck, your audience is often the strongest voice toward a solution. Remember how I noted that my brain has been shorting out? Well, after talking to some of my colleagues, I was able to get the documentation in good working order and ready for delivery.
If you are interested in looking at some ways to use cards, check out the Nielsen Norman Group's article on the same topic. This website was my gospel in grad school, and I can guarantee that you'll find something useful among its content.
And if you're looking for remote-friendly card-sorting tools, consider these options:
General posts useful to all documentarians about writing documentation, editing and publishing workflows, and more.
Your flight plan for how to get the most out of KnowledgeOwl features and integrate them into your workflows.
Major KnowledgeOwl company announcements.
Learn how others are using KnowledgeOwl & get pro tips on how to make the most of KO!
Find out more about who we are and what we value.
We believe good support is the foundation of good business. Learn about support tools and methodology.
Learn more about tools to solve various documentarian issues, within and beyond KnowledgeOwl.
Not sure what category you need? Browse all the posts on our blog.
Watch a 5-minute video and schedule time to speak with one of our owls.