Tag: Justin Baker

Posted on

The Impact of XML on Technical Editing

Justin Baker

I remember hearing a lot of chatter at the beginning of this decade about something called XML. I remember hearing about the unknown implications for editors: Would the paradigm of structured documentation and single-sourcing models make editors all but obsolete? I saw myself in a museum behind thick glass. Because of this thing called XML, were we all doomed to go the way of the Gutenberg press?

Well, hardly.

I’ve learned a little about XML over the last seven years, and I feel a little more at ease. To understand XML’s impact on technical editing, let’s first look at a brief overview of the major editing phases of linear-based documentation. We will then examine the nature of XML before finally moving on to how XML affects technical editing.

Linear-based documentation (traditionally called paper-based documentation), has three major editing phases in my own mental editing model: (1) Knowledge Editing, (2) Language Editing, and (3) Layout Editing.

  • Knowledge Editing refers to the technical subject matter in a document both in verbal form (words) as well as in visual form (images). I divide Knowledge Editing into four sublevels: Knowledge Accuracy, Knowledge Completeness, Knowledge Logic, and Knowledge Hierarchy. The first two editing sublevels ensure that the subject matter is accurate and complete. The third editing sublevel ensures that the basic logic of the subject matter is sound, and the fourth editing sublevel ensures that the 1.0, 1.1, 1.1.1 hierarchy of the subject matter is sensible.
  • Language Editing refers to the technical subject matter in a document both in verbal form and visual form. Language Editing focuses on the exposition of the knowledge through words and images. Language Editing encompasses sentence structure, grammar, diction, punctuation, spelling, and character mechanics (font and display attributes). Language Editing focuses on the particular standard visual elements to be used in any given type of illustration. For example, for network diagrams, some companies might want to consistently use the same network-server icon. Language Editing ensures that both the verbal language and the visual language are standardized.
  • Layout Editing focuses on the following document areas:
    • Industry-standard, large-scale document page layout patterns (for example, a traditional template for a specific industry project plan)
    • Text and illustration spacing
    • Large-scale font formatting (small-scale, or individual, font formatting is part of character mechanics under Language Editing)
    • Miscellaneous layout mechanisms such as running headers, page numbers, and hyperlinks

Now that I have laid the editing foundation for this examination, let’s examine the nature of XML before we see how it affects the editing model.

XML (eXtensible Markup Language) is a metadata language that allows you to tag a chunk of text with labels that explain the nature of that chunk of text. XML promotes the use of tags that indicate “this is a name” or “this is an inventory part.” XML also controls the structure of a document to a large degree. Using the same set of labels, or XML tags, you can dictate the pattern of particular chunks of text. Perhaps you simply have a set of XML tags that are “heading” and “paragraph.” You can dictate rules for the structure of the document such as a paragraph must always appear right after a heading or a figure can never appear without a caption. The library of XML tags and the organizational rules for their use within a specific document is referred to as a document type definition (DTD) or an XML schema. So, we have tags that describe the nature of chunks of text within a document, and we have restrictions about how the document can be structured.

For the purposes of this article, there is at least one more way that XML can control a document: layout. A complimentary standard of XML called the XML Stylesheet Language (XSL) can dictate how particular XML tags are displayed. While XML focuses on describing the nature of text, XSL dictates whether a chunk of text appears bolded, or centered, or whatever. With XML and XSL, the nature of text and the formatting of text are kept completely separate.

So how does XML affect technical editing? Well, XML doesn’t control every aspect of technical editing to the point that you and I are relegated to the role of spellchecker, but XML does take a significant amount of control away from the technical editor.

How Does XML Affect Knowledge Editing? XML cannot control the accuracy or completeness of text. Unless XML is instilled with artificial intelligence in the future, it never can, and it never will. However, XML does control knowledge logic and hierarchy to a degree. For example, an XML DTD can control whether chunks of text tagged with a paragraph tag can occur after chunks of text tagged with a heading tag. However, XML cannot control the logic and hierarchy within the tagged chunks of text.

The XML DTD may be able to control the structural logic of the text to some rudimentary degree (for example, the pattern of tagged text must be heading-paragraph-heading-paragraph-subparagraph), but it cannot control the substantive logic within a paragraphs or within a sentence. You could have what is called a well-formed XML document, in which the pattern of heading text chunks and paragraph text chunks satisfies the rules of the XML DTD, but those text chunks could contain complete gibberish, and the XML DTD would not know the difference.

How Does XML Affect Language Editing? XML has the least control in this area. You can tag a chunk of text with a paragraph tag, but that tagging cannot control the sentence structure, grammar, diction, punctuation, or spelling. You can still write a horribly structured sentence, and the XML DTD would never know the difference. Bad spelling could also be rampant in an XML document. As part of the style rules in the related XSL, the character mechanics can be controlled: headings can be made to be a particular font size, case, etc.

How Does XML Affect Layout Editing? This is where XML dominates technical editing across the board. Everything within the layout editing can be controlled by the DTD and the DTD-related XSL: industry-standard, large-scale document page layout patterns; specific text and illustration spacing; large-scale font formatting; and miscellaneous layout mechanisms such as running headers, page numbers, and hyperlinks. With a document developed using XML, the technical editor doesn’t need to focus on these layout aspects. XML allows the technical editor to focus on knowledge and language.

As you can see, XML does not relegate technical editors to the trash bin of technical documentation history. Even with the restrictions of XML, technical writers have a lot of room to maneuver, and therefore a lot of room to make mistakes. Where there are mistakes, there are technical editors. Technical editors are still needed to edit for accuracy and completeness, and to a large degree, a human brain is still needed to ensure correct logic and hierarchy. All the traditional language skills are still needed. Layout is governed largely by XML, but, for those of you who always loathed setting margins and making text bold at a 14-point font size, your day of deliverance has come. Until an XML language is developed with an artificial intelligence that can recognize the illogical structure within any given sentence or that two sentences have been turned around, a technical editor will be needed.

Posted on

Keeping up with the Joneses (or Is It Joneses’s?)

Justin Baker

It’s important to keep up with your fellow technical communicators; one should be up-to-date on all of the latest advances in the technical-communication profession. But sometimes we can get too caught up in the latest professional advancements—XML, DITA, information architecture, online help systems, metatags, user-interface eye tracking, etc.

Among all of these sophisticated, bewildering advancements, verbal text (words and paragraphs) is still one of the basic building blocks of technical communication, and good grammar is what makes verbal text solid and valuable. As a result, a good grammar refresher is needed from time to time.

There are many educational tools that can provide such a refresher. One tool that I have found particularly helpful is the Bedford/St. Martin’s Exercise Central 2.0 Web site (http://bcs.bedfordstmartins.com/exercisecentral/(external link)). As you may know, Bedford St. Martin’s publishes the informative Handbook of Technical Writing. When you access the Exercise Central 2.0 home page, you will notice that you have to log on to the Web site. To do so, you need to sign up as a either a student or an instructor—don’t let this deter you. Sign up as a student. If you don’t log in, only limited content will be available to you. (Note: I contacted the Web site’s staff to determine if use of their Web site by common users is a violation of their policy; a staff member stated that it is not against their policy for the Web site to be used by someone who is neither a student nor an instructor.)

Once you are logged in to Exercise Central 2.0, it will be important to note the Tutorials and Exercises hyperlinks under the Web site’s banner at the top. These sections will provide you the educational meat you’re looking for. (The Diagnostic and Scorecard sections are primarily for students and instructors who need to view reports of exercise scores.) The Tutorials section gives you a great refresher on common grammar rules (in addition to usage and style issues), so take that first if you are particularly rusty on grammar. After you have taken the tutorials, the Exercise section allows you to test your grammar knowledge. The exercises are usually 10 questions each with easy option clicks to speed each exercise along. Simply click Submit once you are done with the questions, and you immediately get your score. Exercise Central 2.0 is a very lean, easy method for exercising your grammar knowledge.

Another tool that I have found particularly helpful is Diana Hacker’s Grammar Exercises Web site (http://bcs.bedfordstmartins.com/rewriting/ge3.html(external link)), which is related to Hacker’s book A Writer’s Reference published by Bedford/St. Martin’s. Again, these exercises serve as a refresher on more than just grammar (if you consider grammar in its strictest definition: how words and phrases function in relation to one another to form a coherent language); exercises on usage and style (word choice and sentence style) are also present. Unlike Exercise Central 2.0, these grammar exercises do not require registration. You are prompted to provide a name each time to sign on, but, technically, you don’t even have to do that. Once you have selected an exercise from the exercise menu, either type a name (any name), and click Begin, or don’t provide a name, and click Begin. Diana Hacker’s Grammar Exercises has a slightly more contemporary instructional design with the employment of hyperlinks rather than option buttons, but the overall design is the same—10 questions with easy answering for a streamlined educational experience.

Sometimes our heads can get lost in the proverbial clouds of technical advancements, especially publishing-format advancements. It’s important to periodically ground ourselves and remember some of the basics of our profession. Those basic building blocks include verbal text and grammar. Bedford/St. Martin’s Exercise Central 2.0 and Diana Hacker’s Grammar Exercises can help you get reacquainted with those building blocks.

Posted on

Clarity for Editing

Justin Baker

When I was a young technical editor, I was confused by all of the technical editing stages within one editing model — not to mention the competing editing models.

Everywhere I turned, there seemed to be a competing name and a competing label for a particular aspect of editing. For example, substantive editing means developmental editing unless you are thinking of a particular editing model.

I was like a movie character in one of those old cliched film montages where the character walks past one blinking neon sign after another, completely perplexed. To this day, I still do not adhere mentally to The Levels of Edit 1 with its nine editing levels. I have sought to develop my own editing model based on my experience as a technical editor. Some theoretical physicists believe that the underlying formula that explains the theory of everything in the universe will turn out to be a simple, elegant formula. Life is indeed complex, but at the mountaintop of knowledge, things must have a simplicity that is understood by all. I believe that to be true of the levels of edit.

If some editors are not clear on the levels of edit that it takes to edit a document, then most managers are certainly not clear on the levels of edit, either. As we all know, communicating our profession’s conceptual models to managers is very difficult. Most managers (excluding technical communication managers) think of writing and editing as a black box activity. They see the document go in; they see the document come out. Most managers are blissfully ignorant of the complexities of our job. Their blissful ignorance may be partly our fault. Perhaps we have not communicated the nature of our activities in the simplest possible way.

This is a usability issue. We as technical communicators are focused on usability more and more, so when the conceptual models in our own profession are not easily understandable, then we need to simplify them. I think it is time to simplify and re-label the editing levels so that they are straightforward and intuitive, at least at the top level. The Levels of Edit espouse no less than nine editing levels, and labels for some of these editing levels are surely not intuitive to either some editors or managers. Let’s simplify the editing model down to three editing levels at the very top.

Knowledge Editing

I propose that the first editing level be titled knowledge editing. Knowledge editing refers to the technical subject matter in a document, both in text form as well as in illustration form. In the editing model I propose, the knowledge editing level would be divided into four sub-levels:

  • knowledge accuracy,
  • knowledge completeness,
  • knowledge logic,
  • knowledge hierarchy.

The knowledge accuracy and knowledge completeness sub-levels would ensure that the subject matter is accurate and complete. The knowledge logic editing sub-level would ensure that the a-b-c logic of the subject matter is sound. The knowledge hierarchy editing sub-level would ensure that the 1.0, 1.1, 1.1.1 hierarchy of the subject matter is sensible. Of course, the editing sub-levels in this editing level might be performed at the same time as they might be in the proceeding editing levels.

Language Editing

I propose that the second editing level be titled language editing. Language editing refers to the technical subject matter in a document, both in text form as well as in illustration form. Language editing would focus on the manifestation of the knowledge through words and images. This level of editing would encompass the following editing sub-levels:

  • sentence structure
  • grammar, diction
  • punctuation
  • spelling
  • character mechanics

For visual text, language editing refers to the particular standard visual elements used in any given type of illustration. For example, use case diagrams use particular industry-standard visual elements that must be used in the diagram; for network diagrams, some companies might want to consistently use the same network server icon. The language editing level would ensure that the text language as well as the visual language are standardized.

Layout Editing

I propose that the third editing level be titled layout editing. Layout editing focuses on the following editing sub-levels:

  • standard, large-scale document structures
  • text and illustration spacing
  • large-scale font formatting
  • miscellaneous layout mechanisms such as running headers, page numbers, and hyperlinks

 

Conclusion

In the editing-level conceptual model that I propose, I do not consider it necessary to build in a layer that prioritizes the levels of editing as is dictated in The Levels of Edit or a Council of Biology Editors (CBE) publication2 from several years ago that proposed the reprioritization of the editing levels found in the Levels of Edit. Simplicity is best in this situation. It is enough to give technical editors the basic editing levels and sub-levels and let them decide what takes priority.

I have not covered all the possible nooks and crannies of the editing landscape in this brief column, but it doesn’t matter. Even if I had covered every single aspect of editing, there would be arguments about the arrangement of the editing levels and sub-levels. The point is that the editing conceptual model needs to be simplified at least at the top editing level. I say knowledge editing, language editing, and layout editing. You may say something else. And we can debate on the editing sub-levels that lay beneath. I’m merely making a call for clarity.

Justin Baker has been a technical writer and editor for nine years. You can reach him at bakerjustin@earthlink.net.

Endnotes

  1. Van Buren, Robert, and Mary Fran Buehler. The Levels of Edit, 2nd Ed. Pasadena: Jet Propulsion Laboratory California Institute of Technology, 1980.
  2. Nadziejka, David. 1999. Council of Biology Editors Guidelines, Number 4: Levels of Technical Editing. ISBN 0-914349-5-0. Reston, VA: Council of Biology Editors

Reprinted from Capital Letter(external link), the newsletter of the Washington, D.C. chapter of STC, by permission of author and editor.

Posted on

The Punctuation Revolution: A Review of Eats, Shoots & Leaves

Justin Baker

A panda walks into a cafe. He orders a sandwich, eats it, then draws a gun and fires two shots in the air. “Why?” asks the confused waiter, as the panda makes towards the exit. The panda produces a badly punctuated wildlife manual and tosses it over his shoulder. “I’m a panda,” he says, at the door. “Look it up.” The waiter turns to the relevant entry and, sure enough, finds an explanation. “Panda. Large black-and-white bear-like mammal, native to China. Eats, shoots and leaves.”

Continue reading “The Punctuation Revolution: A Review of Eats, Shoots & Leaves”