Aviva Garrett, Juniper Networks

In last month’s e-newsletter, Alexia Idoura of Symantec asked what we, as managers and innovators, can do to help our employees and colleagues who are struggling with moving from the model of presenting product information in linear books to a non-linear model of information connected by hyperlinks. She asked how we can help people make “the leap from a linear to a hypertext/help/web/topic/modular model” to “

[t]hinking in terms of maps, not outlines. Thinking in terms of hypertext, not linear blocks of prose with seemingly infinite layers of nesting.”

She asked about people who are struggling with a paradigm shift, a thought-process shift in how they fundamentally approach their job and their profession.

Contributors to the listserv discussion offered a range of useful suggestions. In this article, I talk about two:

  • changing our vocabulary
  • using the Google paradigm as a model for topic-based documentation

It has been my experience as a writer and manager that most writers (and managers) are so grounded in the idea of writing books, with pages, cross-references, and indexes, that they can’t wrap their heads around the idea of writing modular or topic-based documentation that is connected by hyperlinks, and supports findability through a search engine. Many writers also don’t understand the architectural structure of the information they write. Instead, they view their work as a series of somewhat related sentences. Most writers expect to control completely the format of information on a page and cannot at all grasp the concept of separating content from presentation.

Changing the vocabulary

An important part of enabling strugglers to understand module and topic-based documentation is to change our vocabulary. If we continue to use old words for new concepts, we continue to foster the idea that old ideas—such as books and modular writing—are the same as the new ideas—such as information products and topics. Worse, we confuse everyone (including ourselves) because we use the same terms to mean two different things. Instead, we should use our knowledge of controlled language and simplified English, which tell us to write unambiguously by defining our terminology clearly, ensuring each term has only a single meaning, and then using our terminology precisely.

For this to work, there are three basic steps that you as a manager or innovator, need to take:

  • First, choose new terms and names that work for your organization, terms that are different from what you are currently using.
  • Second, clearly define the new names.
  • Third, and perhaps most importantly, translate the new name into the old name.

The first step creates unambiguous terminology, the second step provides “one term, one meaning,” and the third step provides the pathway from the old to the new.

I can illustrate this process with my current work. At Juniper Networks, we have been working with an information architect, who has been analyzing our books in an effort to transform them into topics. Using her language, we have information products (old name: books) that consist of a number of topic families (old name: chapters), which themselves consist of topics or articles (old name: sections). Now, I no longer tell the strugglers that they will be writing topics to include in the chapters of a book, which might lead them to wonder how this is different than their current work process. I tell them that they will be writing topics that will be part of a tightly coupled group of standalone articles (the topic family). We will then assemble loosely coupled topic families into information products. The information products will have a table of contents or something similar, and they will likely look very much like books (but then again, they may not).

Because we use the word topic to mean a stand alone article of technical information, one side effect is that we cannot use the term in other contexts. For example, we cannot say that customers “use the search engine to find information about a particular topic.” We have to use another term, such as feature or subject. It does take a bit of adjustment to use your chosen vocabulary precisely!

I would like to highlight a second term that I have been using. I believe that for Juniper’s documentation, and perhaps for your documentation, vocabulary cannot simply be converted from a book paradigm or from a modular writing paradigm to a topic-based paradigm. The word “convert” implies a one-to-one straightforward mapping process. Instead, I believe that to create true topic-based information products, we must transform not only our existing content but the thought and planning processes we use to understand our customers and to create our content. If your strugglers can understand this transformation, they may be able to reset their expectations about the nature and results of the change. The new thought process may be the catalyst they need.

Experiencing a Google-based search

A second idea to help the strugglers is to simulate an environment in which they are the customer rather than the technical communicator. The simulation uses a Google-based exercise in which people look for information on the web, perhaps about how to repair or get service on a particular vacuum cleaner. This type of search is exactly what our customers want: they type a question or phrase into a search engine, whether it’s Google, Google Desktop, or your corporate search engine, and they expect that one of the first several results contains the relevant answer. This idea is based on one of the stories related by Malcolm Gladwell in his book The Tipping Point, that tells how the NYPD chief made all police department managers ride the subway to work so that they would fully understand the complaints of the subway riders and be able to participate in improving the subway-riding experience.

We visited Juniper customers last year to ask about our documentation. A surprising finding was that customers don’t use books and don’t even think in terms of books. They use search engines. They use the Google paradigm to find information: they type a question or string in a search engine and want their answer to be one of the first three results. If you can get your strugglers to understand this mindset, they might begin to get a glimmer of how to construct standalone topics and modules. I think that everyone uses a search engine of some kind in their work and private lives, so everyone should be able to relate to the Google experience.

I believe that over time, most strugglers will understand the difference between books and information products and between linear chapters and interrelated topics, and will be able to make the leap to a new way of thinking. However, as some on the listserv discussion mentioned, we will always have some strugglers who will never be able to make this leap. It will be our job as managers to help them find a role in which they can be successful, whether it be within our department or company or elsewhere.

Share your ideas!

If you have a topic you think would make a good article for a future issue of the e-newsletter please send it to taj.whitesell@comtech-serv.com. Articles are typically between 500 – 1000 words in length. We look forward to having our e-newsletter readers weigh-in!