The Door Marked “Enter”: Transitioning from Manuals to Web Content

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 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 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.

Suggestions for Adjusting to the New Content Paradigm

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.

• Give the user a reason to stick with your content: Remember that most users won't read a document end-to-end. In our search-based culture, they type a term into Google to search the entire web, and then they apply filters to the results. This may not be how you want users to find your content, but the sooner you embrace and write/plan/design for this practice, the better!

  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:

  • Don’t imply context; always spell out the article context, address a common question or issue, and 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.

2. Use the processes that work for you but be prepared to rethink everything: anything that is book-friendly isn't necessarily 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 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.

• 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).

3. 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.

4. Talk to users: The web flattens more than just content. It takes away the voice of authority in favor of the voice of experience. A user who isn’t happy will make it known; see it as an opportunity to improve your 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.
5. Embrace change and constraints: Shifting paradigms is always hard, for everyone involved. As a team, expect headaches inside the team and around you for a while. 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 about Knowledge Base Web Content and SINGLE-TASKING

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.”

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!) about 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