From Manuals to Articles
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 actually respond to real feedback.
Instant Information (Overload)
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 all of the web and then filtering it 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 new (not really new) type of information seeking habit.
Suggestions for Adjusting to the New Content Paradigm
If your team was responsible for documentation sets that 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 you don’t need to dispense will all the knowledge you’ve accrued; best of all, your desire to help users will continue to be 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.
- Give the user a reason to stick with your content: Remember that most users are not going to read a document end-to-end. In our search-based culture, they are typing a term in to Google to search the entire web, and then they will apply filters on the entire web. This may not be how you want users to come to the content you work on, but the sooner you embrace and write/plan/design for this practice, the better!
What matters is what a user invests in content that they’ve come to from a search. To them, 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). As soon as they arrives at a page, if it’s not answering their question or providing a clue, they’re gone in 60 seconds. So:
- Don’t imply context; always spell out the article context, address a common question or issue, provide a map of other resources (helpful links).
- The web is flat: avoid hierarchies that bury content (and likely make users themselves feel buried).
- Content may coexist with other mediums such as videos, graphical aids, and so on. It’s a good thing.
- Use the processes that work for you but be prepared to rethink everything: something that is book-friendly won’t necessarily translate to web-friendly. That’s not to suggest that you gracefully retire any tools and methods you’re already using:
- DITA/XML authoring for knowledge bases? Check.
- Best practices like reuse for knowledge bases? Check.
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 will vary depending on your team, resources, and so on, but it’s high time to embrace linking to some extent.
Think through the notion of a “standalone topic”, too.
- Quite often, this concept may refer to a single topic that can be read alone, but in book paradigms it typically cannot exist without the supporting nodes of the book it’s wrapped in and the other topics around it.
- In contrast, consider a standalone topic and what it means on the web: “An article can be read on its own. It is not part of a larger manual. It stands alone not merely by existing separately, but by functioning separately” (Baker 74).
Still, use what you know for the benefit of the doc strategy and ultimately your users. You may’ve been involved in content auditing on other projects. Those skills are useful for knowledge base delivery, too:
- Search the web and other competitor knowledge bases.
- Assemble a few samples, note what is effective in each, what isn’t, and
- Synthesize the results to inform your writing team’s strategy.
- Your content may be complete today, but you will revisit it tomorrow: Get used to the idea of lather-rinse-repeat maintenance of your content. You will be making iterative changes (and hopefully improvements!) Cloud-based software development calls it “continuous delivery”; the philosophy applies to content on the web, too, it quickly becomes stale, obsolete, and worst of all, no longer useful.
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.
- Talk to users: The web flattens more than just content. It takes away the voice of authority in favour of the voice of experience. A user who isn’t happy will make it known; see it as an opportunity to improve content, so that the next user in the same boat may have a potential answer.
- Monitor whatever user channels you can get your hands on, especially direct ones like forums, social media streams, case tickets, and so on.
- Get your hands on search metrics to learn user search and retrieval habits.
- Embrace change and constraints: Shifting paradigms is always hard, for everyone involved. As a team, expect headaches inside the team and around you for awhile. Chances are, other stakeholders on the project you’re documenting (and maybe the culture of the organization in general) are changing too; take solace in the fact that you’re not alone, you’re all building something with the intent of helping users, and be empathetic when other teams might seem confused about the strategy that the documentation team is taking.
A Sidenote on Knowledge Base Web Content and Singletasking
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 singletasking. 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 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 at 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. Whatever side of the coin we’re on, distractions are vying for all of our attention – realize that users you’re writing for are in the same boat. Amongst a sea of choice, tools, processes, and pressures, users in 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 uses or moves to, the field of technical communication needs to be dialed into how real users really 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.”
Articles as a Hub
In addition to the links I peppered throughout this post, here are some useful resources from around the web (and one book!) on knowledge base strategy, content on the web, information retrieval habits, and related subjects:
- Good Riddance to the Manual
- One Answer, Many Questions
- The Impatient Reader
- UX for Social Good
- Get Started with Knowledge Centered Support
- Why Long Topics are Better for the User
- Rethinking Inline Linking
- More Links, Less Time
- Incompetent Research Skills Curb Users’ Problem Solving
- Every Page is Page One by Mark Baker
Designing Intelligent Content for AI - Part 1
Welcome to the first of a dual part series on writing for Artificial Intelligence. Let’s begin with...
The Demise of the Manual
“Manuals are rapidly becoming the last items people rely on to find information about the products...
The Future of Technical Writing: from Books to Topic-based Authoring
Is topic-based authoring the future for technical writing?
As technology evolves, so must the...