–Geoff-Hart.com:–Editing, Writing, and Translation

—Home —Services —Books —Articles —Resources —Fiction —Contact me —Français

You are here: Resources --> 2004 --> Editorial: Paying back, scientifically speaking
Vous êtes ici : Ressources --> 2004 --> Editorial: Paying back, scientifically speaking

Editorial: Paying back, scientifically speaking

By Geoff Hart

Previously published as: Hart, G.J. 2004. Editorial: Paying back, scientifically speaking. the Exchange 11(2):2, 7–8.

I was trained as a scientist, but though I briefly contemplated a career in research, I discovered that my real passion was the printed word and later, the online word. Having reconciled myself to the notion that there would be no Nobel prize in my immediate future, I set about learning the trade of editor and honing my passable skills as a writer into a sharper tool. Reading the Chicago Manual of Style cover to cover, and washing that information down with a shot of Strunk and White and a Plotnik chaser, gave me the foundation for the skills I needed to do the new work I was seeking. What was lacking? More formal training in the art and science of communication.

I was fortunate. When I landed my first job, with the Canadian Forest Service, my mentor introduced me to the Society for Technical Communication and budgeted for my membership fee. I soon found a treasure trove of information that could be applied directly to my new profession: an improved understanding of the concept of audience, insights into data graphics through my readings in information design, and a wealth of information in applied cognitive psychology, among many other things. Over the years, I've deepened my insights into these and many other fields; better still, I've learned to apply the techniques of technical communication to my work in scientific communication. I've also joined a community of kindred spirits who have nurtured me and given me an opportunity to nurture others in turn, which is arguably the greater gift.

STC's near-total lack of focus on anything to do with scientific communication has made membership even more useful. Some friends have argued that membership in a science-focused organisation such as the Council of Science Editors or the National Association of Science Writers would be a more effective way to hone my skills, and there's certainly some merit to that suggestion. But I'm already immersed in the practice of scientific communication, and what I wanted more than anything else was an outsider's viewpoint—one that would provide a whole range of different skills and attitudes that could be brought to bear on the problems I face as a scientific communicator. The isolation of the scientific communication community does provide a more focused range of expertise, but leads one to internalize that commmunity's prejudices and received knowledge. That kind of acculturation makes it much harder to bring new insights to bear on one's work. STC provides an antidote to a potentially insular world view.

There's much that we scientific communicators can learn from STC, particularly in the fields of information design and audience analysis. But what could STC learn from us? Let's consider just one simple example of the kind of things scientific communicators do better than anyone else, and how the related skills could be transferred to other branches of technical communication.

The schema of journal articles

The peer-reviewed journal article has a standard structure so well known to scientists that experienced readers can use its schema (mental model) without conscious thought to gain entry into the information stored in an article. The form in which the information is presented matches its intended use so closely that it's hard to imagine the kind of breakthrough that would lead to an improved design. Yet if you compare journal articles with (say) software user manuals, it rapidly becomes apparent that no such standard schema exists for documentation. Instead, readers must discover and learn to use a different schema each time they open a new manual.

What if we applied the journal model, suitably modified to fit the new audience and new context, to the task of structuring user documentation? For example:

An abstract summarizes key insights that the larger text will discuss in more detail. Analogous "quickstart" guides and "quick reference cards" exist for some products. Why not make them part of all user documentation?
The Introduction provides an overview of a problem the research community faces and of how other investigators have addressed the problem. Documentation should provide similar introductory information that describes what problems the software has been designed to solve. Yet such overviews tend to be either absent or shallow, and no documentation I've encountered refers to the broader body of pre-existing knowledge that provides context for the tasks supported by the software. Shouldn't desktop publishing software provide a tutorial on page layout and typography?
In a journal article, the Methods and Materials section lets readers assess the validity of the experimental approach, ponder how it might have influenced the results of the research, and repeat the experiment themselves to replicate and thus confirm the results. Documentation rarely includes analogous overviews of the metaphor or metaphors used to structure the software (the methods by which one obtains the desired results) and a discussion of how the input materials affect the use of those methods. Imagine, for example, a word processor manual that discusses effective outlining techniques, then describes how that software implements them.
The Results and Discussion sections (which are sometimes combined) report what the researchers discovered and the implications of these discoveries in the context of the original research problem. A clear parallel in documentation might be descriptions of which techniques work most effectively, situations in which other techniques would be preferable, and where to go for more powerful, more advanced techniques. Consider, for example, the huge market in "how to" books for Photoshop. When the Results and Discussion are separate, the results appear first, without interpretation, so readers can ponder the meaning of the data before having their own interpretation influenced by someone else's interpretation; the interpretation (Discussion) then follows. These sections have clear analogies in documentation: separate reference ("just the facts") and procedural sections (the author's opinion about how to apply those facts), or sections that integrate this material.
The Conclusions present a more detailed summary of the key points presented in the Abstract, explore their limitations, and present a call for additional research. In documentation, this section could easily become an expanded Quickstart guide, or an indication of where the current software ends and what other software can take you beyond that point. For an example, consider a word processor manual that explains the difference between its own table functions and the more powerful ones offered by spreadsheet software.
The Literature Cited section in a journal article provides references to published information by other authors that supports the author's overview of what is already known, justifies the author's research approach, and supports (or contradicts) the author's findings. In documentation, the equivalent might be background material (e.g., references to classic textbooks in photography for users of Photoshop), "best practices" (e.g., cookbooks of standard programming algorithms for software developers), and references to other useful books that go beyond the scope of the current documentation (e.g., references to the "Missing Manual" series of books published by O'Reilly and Associates).

Paying back (and forward)

No one approach fits all situations, and the journal article schema clearly isn't a perfect match for user documentation. The power in my example lies in considering each of the strengths of this schema, in discerning the underlying principles that give rise to each strength, then applying those principles to the task of improving user documentation. In my example, I've listed seven components of a journal article and briefly discussed their principles and how these principles might be applied in technical communication. Let me now issue a challenge: How can you apply those principles to the types of task a typical STC member might have to accomplish? How have you applied these principles?

If you have any insights, disagree with any of my assertions, or want to expand on what I've written, The Exchange would be a great place to do so. I've long wanted to start an ongoing dialogue on how we can apply the techniques of scientific communication to other forms of technical communication. Conversely, if you've learned something from STC that applies to scientific communication, why not share it with other members of the Scientific Communication SIG? There's plenty of room in our newsletter for a broader range of voices, and I'd be pleased indeed to offer you that room in which to share your own insights.