So you’re moving from delivering book-based content to web-friendly content in a knowledge base portal. It’s going to be a bumpy ride, but well worth it! Be prepared for a frenetic pace, a lot of (daily) challenges, but also a lot of (daily) rewards too – not the least of which is being able to help users that much more with searchable, web-friendly content, and being able to respond to real feedback.
I won’t rehash the history and demise of the manual, but consider this quote: “The challenge for technical communicators, especially those who have spent a career writing books, is to think of their project as a set of independent topics” (Baker 135).
Suffice to say: we live in a Google search world; people want answers and they want them now. While there’s still value in books for deep learning, manuals written as books were arguably never conducive to the “I’m stuck, I need answers” approach to learning. In that situation, users are typically reading to do, not reading to learn: “Users dive into a product, work till they get stuck, and then look for quick answers to get them unstuck” (Baker 5). This is done by searching the web and then filtering the results down, not by reading a book cover-to-cover.
Despite these search habits and the web content that embraces these habits (forums, blog posts, social media, Wikipedia, and so on), the book paradigm persists in the technical writing field. Truly, we’re creatures of habit, and old habits die hard!
We in the technical writing industry need to embrace this information-seeking habit.
If your documentation sets are attached to waterfall projects or larger documentation sets in general, the shift to a knowledge base or web-friendly delivery will be pointedly felt. Rest assured that your accrued knowledge and desire to help users are still valuable in this environment.
If there’s one thing you take away, let it be this: everything you write should be a big “enter” sign for users. That’s all they’re looking for.
Spoiler alert: These suggestions don’t just apply to knowledge base content. Consider them for any web-based documentation effort.
To users, every page is page one: “Each page is the hub from which all subsequent exploration of the content will begin, and upon which your ability to influence readers depends” (Baker 60). If the page doesn't answer their question or provide a clue, they’re gone in 60 seconds. So:
But consider a rethink: For example, in book-based guides, some groups may be told to avoid linking, which creates dependencies between topics. Content on the web, however, is all about the links. The method varies depending on your team, resources, and so on, but it’s high time to embrace linking to some extent.
Reconsider the notion of a “standalone topic”, too.
A great lather-rinse-repeat method is the knowledge-centered support approach, whereby content becomes a way to solve issues, not something in addition to solving issues: 1. Use it, 2. Flag it, 3. Fix it, 4. Add it.
This idea may seem overwhelming, but there’s good news: if you keep the content in manageable units (topics), they’re easier to update than a book of building block topics. “There may not be time in the cycle to fix all of the topics, but there is always time to fix the topic you are working on” (Baker 231). I see this as a benefit to both writers and users; book-based documentation sets are typically locked down, with no opportunity to improve them until the next release. Plus, retiring content that’s fused into a book is a lot more challenging than retiring a single, standalone article.
At a glance, the proliferation of content streams on the web may suggest a celebration of multitasking; however, I think when it’s most effective, it encourages single-tasking. Think of a deck of cards; when scattered, they’re fragmented and individual; when assembled, they show patterns and connections. I feel that effective content on the web should follow suit (pun intended).
Mark Baker talks about the downsides of switching back and forth: ” switching back and forth between topics […] creates cognitive overhead and makes it difficult to get into, and stay in, a state of flow, which is necessary to effectively and efficiently complete an intellectually demanding task” (150-151). That’s addressed to writers; if fragmented content without context is the outcome, that affects the user base looking for help, too. With effective knowledge base content planning and feedback cycles that are dialed into the user, even the individual cards show the connection to the larger deck.
Technical writers have always kept user goals in mind. More than ever, that must be the starting point – even the obsession – of the field. Distractions constantly vie for all of our attention – realize that users you’re writing for are in the same boat. In a sea of choice, tools, processes, and pressures, users at any given moment are still trying to complete that one thing to get their job done. Good context, findable content that empathizes with users and guides them through rocky terrain – all of this adds up to an “information scent” that users will hopefully follow rather than “switching back and forth” from content to web searches needlessly.
Whatever content strategy you and your group use or move to, the field of technical communication needs to be dialed into how real users find content on the web today, and that’s chiefly through search and skim, not sitting down to read documentation end-to-end. The sooner our field accepts that, the more we can help users find the door marked “Enter.”
In addition to the links I peppered throughout this post, here are some useful resources from around the web (and one book!) about knowledge base strategy, content on the web, information retrieval habits, and related subjects: