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

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

You are here: Articles --> 2005 --> Scientific documentation: learning from journal articles

Vous êtes ici : Essais --> 2005 --> Scientific documentation: learning from journal articles

Scientific documentation: learning from journal articles

By Geoff Hart

Previously published as: Hart, G. 2005. The scientific method: learning from scientists. Intercom March:14–17, 47. [Based on the author's editorial in the April 2004 issue of the Exchange, the newsletter of STC's scientific communication SIG]

I was trained as a scientist, and although I briefly contemplated a research career, I soon discovered that my real passion was the printed word—and later, the online word. Early in my career, I joined STC for a reason that may seem odd at first glance: STC's near-total lack of focus on anything to do with scientific communication. I felt that I was already immersed in the practice of scientific communication, and I wanted an outsider's viewpoint that would provide a range of different skills and attitudes that I could bring to bear on the problems I faced as a scientific communicator. Recently, I began wondering what STC could learn from my chosen profession. The answer may lie in something that scientific communicators do better than just about anyone else: produce journal articles in a standard format that is instantly recognizable to (and easily usable by) any scientist. Wouldn't it be nice if user manuals worked that well? Perhaps they could, if technical communicators borrowed a few tricks from scientific communicators.

The journal article model

Peer-reviewed journal papers in the sciences follow a standard structure that, despite the occasional idiosyncratic variation developed by a specific journal, is intimately familiar to any scientist. Experienced readers can use the schema (mental model) of a journal paper almost without conscious thought as a means of gaining entry into the information stored in the paper. The form in which the information is presented matches its intended use so closely that it's now hard to imagine the kind of breakthrough that would improve the design, though there's certainly room for improvement in terms of language and accessibility (e.g., the use of indexes for long monographs). For those who aren't familiar with the journal schema, here's a summary of the contents and order of the sections in every paper:

Papers begin with an Abstract that summarizes the key insights that the body of the text will discuss in more detail. An Introduction then describes a specific problem that the research community faces, how other investigators have addressed the problem, and what work remains to be done (e.g., by the research reported in the paper). This is followed by a Methods and Materials section that lets readers assess the validity of the experimental approach, ponder how that approach might have influenced the results of the research, and repeat the experiment themselves to replicate and thereby confirm (or contradict) the author's results. Results and Discussion sections (sometimes combined) report what the researchers discovered and the implications of these discoveries in light of the original research problem the author set out to solve. There may also be a separate Conclusions section that presents a more detailed summary of the key points presented in the Abstract, explores the implications and limitations of these findings, and presents a call for additional research, if such is merited. Last but not least, a Literature Cited section 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 or explains it in more detail, and supports (or contradicts) the author's findings.

Contrast this with (say) software user manuals, where it rapidly becomes apparent that no such standard schema exists. Instead, readers must discover and learn to use a different schema each time they open a new manual. If the schema of a journal paper is so effective for scientists, what lessons does it have for other technical communicators?

"Scientific" user manuals

Each of these sections of a journal paper serves a specific purpose that has parallels in user manuals and other forms of documentation. Here are some examples for one specific communication context, that of the manuals we create for computer software:

In place of the Abstract and Conclusions, we could provide a "quickstart guide" or "quick reference card" that outlines how to use the most important features. An expanded Quickstart guide could focus on the 20% of the features that the users apply 80% of the time, or could indicate where the current software ends and what other software exists to 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, and proposes the integration of two different programs (e.g., Microsoft Word and Excel) to create synergies. Such guides exist for some products, but why not make them a feature of all user documentation?
In place of the Introduction, documentation could provide an overview of the problems the software has been designed to solve. Where such overviews exist, they tend to be shallow, and never refer to a broader body of pre-existing knowledge that provides context for performing the tasks supported by the software. For example, desktop publishing software could provide a tutorial on page layout and typography that teaches users apply the software's tools wisely. Instead, most software manuals assume you already possess this knowledge—a dangerous assumption.
In place of the Literature Cited section, which supports the material in the Introduction, documentation could include references to important background material (e.g., classic textbooks in photography for users of Photoshop), to "best practices" guides (e.g., cookbooks of standard programming algorithms for software developers), and to other useful books that go beyond the scope of the current documentation (such as the "Missing Manual" series of books published by O'Reilly and Associates). It might be difficult to persuade one's manager to advertise another company's books, but from the user's standpoint, this approach would add considerable value. Perhaps you could persuade your employer to bundle these reference books with your own documentation for an additional fee?
In place of the Methods and Materials section, documentation could include overviews of the metaphor or metaphors used to explain the software to the user (i.e., 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 and how the word processor implements these techniques, or a manual for image-processing software that explains the different input and output formats (e.g., JPG vs. TIFF).
Most importantly, documentation could replace the Results and Discussion sections with descriptions of which techniques work most effectively under specific circumstances (i.e., how to achieve specific results), situations in which other techniques would be preferable (i.e., a discussion of the alternatives and the limitations of each option), and where readers can go to learn more powerful, more advanced techniques. Consider, for example, the huge market in "how to" books that has developed for Adobe's Photoshop software. When the Results and Discussion are separate sections, the Results appear first, without interpretation, so readers can ponder the meaning of the data before having their own interpretation influenced by the author's interpretation; the interpretation (Discussion) then follows. This is clearly analogous to providing a reference section ("just the facts") followed by procedural sections (the author's opinion about how to apply those facts), or to integrating this material into a combined reference and "how to" section.

Adapting a classic approach

Obviously, no one approach fits all situations, and the schema for journal papers is clearly not a perfect match for user manuals. The power of my example lies in the process of examining each of the strengths of this schema, understanding the underlying principles that give rise to each strength, then determining whether it's possible to apply those principles to the task of improving user documentation. As demonstrated in this article, applying this approach to the various components of a journal paper provides some interesting insights into how we might improve other forms of technical communication. It would be interesting to see other authors explore the relevance of the lessons learned by journalism (newspapers and magazines), graphic arts (visual rhetoric), documentary cinematography (the use of moving images to communicate), literature (the techniques of deconstruction and criticism), and other professions.

User manuals won't all follow an identical schema. They are written for dramatically different products (thus, are used in very different contexts) and often for a highly variable audience with highly heterogeneous communication needs. A standardized approach works for journal papers because the context and audience characteristics are so homogeneous: the goal is always to communicate research results within the larger context of a broadly accepted approach to scientific inquiry, and the audience is always scientists with deep, shared knowledge of a particular field. But even in science, writers take different approaches to communication; textbooks, technical reports, and other monographs may take dramatically different approaches to communicating scientific information.

Instead, what I suggest is that we consider the lessons offered by the scientific journal: Perhaps there are some features that every user manual should have, including some of the things I've discussed in this article. Perhaps each of the sections we currently include in our documentation could be analyzed in a manner similar to the manner in which I've analyzed the journal paper, thereby providing insights into the essential features of these sections. And most interesting of all, perhaps we have much to learn from other fields of communication.