Content Curation: Building bridges between web writing and DITA Authoring

Home/Publications/Best Practices Newsletter/2011 – Best Practices Newsletter/Content Curation: Building bridges between web writing and DITA Authoring

CIDM

December 2011


Content Curation: Building bridges between web writing and DITA Authoring


CIDMIconNewsletterNolwenn Kerzreho, Technicolor IPTV

Stepping into technical communication in 2005, I was surprised by the variety of emerging writing techniques, new areas of expertise, and most of all, buzzwords. I wondered if this was an unavoidable consequence in this “age of communication” or a true diversification in our field.

Moreover, in seemingly desperate moves, the technical writers evolved into technical communicators, editorial specialists, information architects, web writers, content curators, knowledge architects, usability experts, or user assistance specialists—I predict the list will keep getting longer.

A Virtuous Distanciation?

Is this distanciation irrefutable? Are the techniques so different as to justify yet another title? Are the web-writer competencies that far away from those of the technical author? I found out that, most of the time, this was not the case.

Realization started to dawn when I listened to Aurélie Valtat, Online Communications Manager at Eurocontrol, talking to students on web writing and web site design. She was invited to the Université Rennes 2 to speak to the Master’s degree technical writing and communication program. She talked about contextualization, chunking, writing intelligible titles, and taking care of navigation, all of which made perfect sense to me, as a DITA author.

When I attended Linda Urban’s training on topic-based writing in Paris, my first impression was confirmed and turned into conviction during the minimalism workshop with JoAnn Hackos.

Yes, minimalism, structured writing, modular writing, and adaptation to your audience can apply in different frameworks. Attending conferences and training on DITA, web writing, user assistance, and content strategy, it came to my attention that these claimed pillars of DITA were also the pillars of technical communication (including web writing), and that sometimes, buzzwords were only… buzzwords.

This article presents the core skills expected when authoring DITA topics and online content (see Table 1).

Tech Writer Web Writer DITA Author

“Content is king”

(special conditions apply)

X X X

Minimalist
approach

(provide the information needed, no less, no more)

X X X
Tell-tale structure and information design X X X

Modular

documentation

with enough context

X X X

User/reader

targeting

(writing for

personas)

X X X

Efficient short descriptions

(guidance to

content)

X X X
Reverse-pyramid style Nice to know Need to know

Nice

to know

Table 1: Core Skills When Authoring in DITA

“Content is King!”

Unsurprisingly (or is it?) I have heard this catch phrase from experts in distinct fields of technical communication such as content strategists, technical writers, and web writers.

The DITA specialists claim that because DITA includes print and web support and enables reuse in multiple contexts and architectures—training, online help, FAQs—the content must be particularly well crafted.

Web writers and usability experts concur. Because readers on the web scan rather than read online information, because the content is plethoric and inadequately formatted, because readers hurriedly abandon poor information, the content must be particularly well crafted.

The technical communicators then re-examine the basics:

  • WHO are the users?
  • HOW do they read and handle the information?
  • WHAT do they do with the information?
  • WHY and how do they find this information?
  • WHEN do they search the information, and what is their frame of mind at that moment?

Minimalizing our Content

Users on screens scan the content instead of reading it. You surely have heard or read this catch phrase many times, most probably, although this applies to all formats, in a topic relating to web writing. For web writers, this truly means “every word counts.”

This implies that technical communicators should not only write and design content but also target the audiences and provide the information needed. No less, no more.

Specialists in related fields, such as usability or editorial strategy, may have an outdated image of technical writer techniques: that the author of a printed manual cannot understand web reading, or scanning, or minimalism.

However, it has always been our duty, as representatives of the users, not to overload them with useless or needless information. And as a community, we should highlight this ability.

Interfacing: Structuring our content and designing patterns

The audiences should recognize in an instant if the content displayed is suited to their needs.

Salience of titles and subtitles, consistency between titles and topics, accurate terminology, plain and relevant information, and guidance to the content are all the essence of technical communication.

Design of the pages themselves must be instantly recognizable visually: a task with numbered steps, a navigational topic with links, a resource to download with the suitable icons, a link design with expected aids, and a visual communication with clear and simple messages.

Layout and structure are part of the technical communicators’ responsibility. When we are building a DITA topic, designing an instruction manual, or a web site information architecture, we are in fact creating an interface that must be accessible and readable. What use is an index or an information structure if it does not provide a functional access to information?

Chunking our Information

To implement modularity, technical communicators must trim down the messages. This is minimalism. The corollary is to write “bite-size” topics. This material change is sometimes also called chunking, applying modular design, or topic-based writing.

Technical communicators are expected to provide one subject per topic, stating a clear objective for the information type—a basic writing skill.

Researchers have pointed out there is no reading order for most users. Absence of a reading order is emphasized in web writing where the information is easy to collect: users scan a web page after a search. They do not start reading a web site from the welcome page on. The same applies for other technical communication: users will not start reading a manual at the cover page but search for the piece of information they need at that moment. Navigation and context must be provided to match this behavior in both cases.

As Linda Urban pointed out, the concept of chunking is not new to technical communicators. Anyone writing a series of highly structured articles, instructional guides, online help, or a blog, has de facto been writing standalone topics.

Adapting our Content to Users

Users are regularly “re-discovered” in new trends for technical communication such as content strategy or information architecture. The idea of user validation and testing is a strongly recommended requirement in Agile methodologies!

Advocates of web writing claim user targeting is even more critical on the web than in traditional technical documentation: the users’ attention span is shorter, the screen degrades readability, readers make up their minds in a (very) few seconds after the page or site displays. These specialists remind us that we should adapt our content to the targeted audience.

Content, style, and terminology adaptation is a core ability in the technical communication field. Technical communication design included personas for years before information strategy stepped in.

Crafting Efficient Short Descriptions

Using short descriptions for topics is expected in DITA. Short descriptions and their uses can be found in journalism practice that dates back over a hundred years.

However, because a short description is required by your manual of style or your DITA style guide does not mean the information is efficient. Even when not using DITA, technical communicators must remember how the audience reads the topic: from the top down.

As stated, the short description and the titles should provide enough guidance and information to the users. The short descriptions must enable readers to choose if they want to read on or search for another topic.

Promoting the Key Message (Reverse-pyramid Style)

Reverse-pyramid writing implies you put the zest of your topic first and expand the information later in the body of the page.

In web writing, the content below the fold, that is, below the initial screen area, is sometimes not even seen by the readers. Typically, older and less experienced readers will not scroll down web pages.

Again, this technique is known to technical communicators and should not come as a surprise when moving to web writing or exploring DITA syntax.

Adding Zest to the Core!

Yes, buzzwords are plentiful in our field: information strategy, content curation, agile methodology, web writing, pattern design, usability, information structure, and so on.

This new terminology should not alarm technical communicators. We are well prepared to track down appropriate contexts, variants, and definitions (a basic terminology practice).

Simple, structured content and targeted and relevant information is a sign of high quality information. Core skills and techniques are appropriate for many, if not all, areas of expertise. Recognizing and then applying these techniques is essential in our ever-changing field. And we too can add new expertise to the core of our talents! CIDMIconNewsletter

Nolwenn Kerzreho

Technicolor IPTV

Nolwenn.Kerzreho@technicolor.com

Nolwenn Kerzreho is a technical writer at Technicolor IPTV where she leads the DITA adoption effort as a trainer and information architect. An adjunct teacher at the Université Rennes 2 in France, and now in charge of the technical writing course outline, she keeps an eye on new trends in the technical communication field, and has special interests in user-oriented documentation, language industry standards, and XML-based authoring systems.

REFERENCES

Janice (Ginny) Redish

Letting Go of the Words: Writing Web Content that Works

2007, San Francisco, CA

Morgan Kaufmann

ISBN: 0123694868

Andy Bounds

The Jelly Effect: How to Make your Communications Stick

2010, Mankato, MN

Capstone Publishers

ISBN: 0857080466

Tony Self

The DITA Style Guide: Best Practices for Authors

2011, Research Triangle Park, NC

Scriptorium Publishing Services

ISBN: 0982811810

Alan Cooper

The Inmates are Running the Asylum: Why High Tech Products Drive us Crazy and How to Restore the Sanity

2004, Upper Saddle River, NJ

SAMS – Pearson Education

ISBN: 0672326140

Gretchen Hargis, Michelle Carey, Ann Kilty Hernandez, & Polly Hughes Developing

Quality Technical In

formation: A Handbook for Writers and Editors

2004, IBM Press

ISBN: 0131477498

Minimalism, Creating Information People Really Need

<http://www.comtech-serv.com/workshops/minimalism.shtml>

JoAnn Hackos, Comtech Services, Inc.

Topic-Based Writing: Getting Your Feet Wet

<http://www.urbancreations.com/workshops/topic_based_authoring.htm>

Linda Urban, Linda Urban Communications

 

We use cookies to monitor the traffic on this web site in order to provide the best experience possible. By continuing to use this site you are consenting to this practice. | Close