Come to the Summit to Gain a Technical Edge

Technology & Development Track

By Marta Rauch (@martarauch)

Here is your guide to a few of the exciting technology and development topics at STC’s Summit- including the Internet of Things, API documentation, video strategies, content for mobile devices and augmented reality, analytics for big data, tools like Jekyll and GitHub, and code samples for Java, PHP, Python, and Ruby.

And it’s not just about tech. Take advantage of sessions on leadership, design, strategy, and trends as well as receptions, speed networking, a tech comm throwdown, and expos. Afterwards, check out the local attractions – enjoy a baseball game with the Los Angeles Angels and visit Disneyland with a discount exclusively for Summit attendees.

There are too many sessions to mention in one article, so be sure to check the schedule, and then head on over to register. To wet your whistle, here’s a quick sampling of Technology & Development track sessions:

Don’t forget to check the full schedule for additional topics and speakers. See you in Anaheim! #stc16

Eye for Editing: Levels of Edit

I’m stating the obvious when I say that there are many systems that define levels of edit. Some systems define up to nine levels or categories of edit, such as the well-known, pioneering effort to define levels of edit by NASA’s Jet Propulsion Laboratory. But when I started in my current role as editor for a team of K–12 curriculum writers, I implemented a personally derived system of four levels, which are based on the book Technical Editing, The Practical Guide for Editors and Writers, by Judith A. Tarutz (1992). This is also the system I’ve used when proposing and scoping freelance editing projects. My system includes the following levels of edit: Developmental, Substantive, Literary, and Pre-release. Except for Developmental, these levels build on each other, starting with Pre-release at the lowest level.

Because these descriptors don’t have commonly held definitions and because my colleagues are not used to working with a technical editor, I have had to very clearly explain and illustrate how I define each level. After all, it doesn’t really matter what term you use to describe something as long as everyone involved has the same understanding, right? But it has not been as easy to explain as I thought it would be! The process has challenged my own understanding of the levels of edit I’ve chosen. I’ve had to dig deep to be able to defend them even to myself.

I’ll briefly describe here the four levels I use, but I’ll only go into detail on one of them—the one that caused me the most soul-searching to define.

The Developmental edit is actually more like a consultation between the editor and the author or authors. It should occur in the planning stages of a writing project. According to Tarutz, the editor can help frame the approach to deliverable development, check the outline and organization of content, make sure the plan addresses the objectives, and spot any red flags in advance. For my purposes, it’s an opportunity for the editor to be included in the project from the start and to begin to develop a working relationship with the writers. Sadly, I’ve rarely participated in or heard of anyone using this type of opportunity. But I have high hopes of implementing this with my new colleagues!

The Literary edit, as I define it, is the most comprehensive review of content for accuracy, usability, consistency, adherence to style, and logical flow, in addition to everything you would check for in a pre-release or production edit. If your project only allows for one editorial review, this is the type of review I would advocate for.

Because I work with curriculum writers whose backgrounds are in education, not technical writing, they were tripped up by the term “Production” edit, which they associated with multimedia production. This allusion to print production of old was foreign to them. One of the leads suggested the term “pre-release,” so I gladly changed my terminology, because “it doesn’t really matter what term you use to describe something as long as everyone involved has the same understanding.” This type of edit is your last chance to catch those little gotchas that managed to get by everyone who’s looked at the content, including the editor. This may well be your last chance to save face with your readers (not to mention your legal department)! If you have little time to review the content, this is the only type of review you can do.

I’ve discussed these definitions out of order, because I wanted to leave the Substantive review until last. This one was the most mysterious to my management, and I realized I wasn’t quite sure myself where the line should be drawn between the Substantive and Literary levels of edit. I admit that I’ve been editing so long that I typically give it all I’ve got or all that the allotted project time will allow and then some! In practice, the distinctions can be blurred. But quite unintentionally, my boss sparked a revelation by way of her pronunciation of substantive. I had always pronounced it sub·stan’·tive, but she put the emphasis on the first syllable—sub’·stan·tive.

In my mind, I equated substan’tive with substantial, which Merriam-Webster defines as “large in amount, size, or number.” This type of edit is a real slasher! It’s an all-out effort to “fix” everything you find to the point of reorganizing whole blocks of content. (However, it stops short of rewriting the content; it only makes suggestions as to how the writer might rewrite problem passages.)

But when confronted with sub’stantive, I thought of the word substance, which means “the quality of being meaningful, useful, or important”. That certainly adds a different aspect to it. So I looked at the definition of substantive—no matter how you pronounce it—and found both of the following possible definitions: “4: considerable in amount or numbers” and “6: having substance”. Therefore, my definition of a substantive edit has changed, or rather has gelled, to mean a sweeping overall view of the content, as well as a review that concentrates on the substance of the content. Is it “meaningful, useful, and important”? How well does it tell the story it’s meant to tell? I define this level of edit as one that looks at scope and completeness, organization and hierarchy of content, coherence at every level—between sections, within sections, within paragraphs, within sentences—plus everything in a Literary edit. Yes, this distinction feels right to me.

But again, this is my—and now our—system. It’s simply how my team has agreed to define the rules of engagement for the services I offer them. I’m sure you all have your own systems and I’m interested to hear about them. I’m especially interested to hear what you think about my definition of substantive. Do you even use such a distinction? Please let me hear your thoughts…

Paula Robertson, Eye for Editing

Eye for Editing: The Editor as Teacher

How do you think of yourself in your editing role? Is each document, article, topic, or book by the same author or team of writers an isolated editing task? Does each task seem to start from scratch as if you’d not edited that author’s work before? Or is each subsequent edit you deliver informed by your previous suggestions and comments? Do subsequent documents indicate that the writer “got it the first (or last) time”?

In other words, do you think of yourself as a teacher? This mindset doesn’t lend itself as well to one-time edits for an author you never work with again. But if you edit content for the same writers on an ongoing basis, you are in a teaching role by default. Your textbook is the company or department style guide, as well as whatever published style guide you’ve adopted for grammar and usage.

Both the editor and writer are working from the same textbook, but it often falls to the editor to gently, even repetitively remind the writer what’s in the textbook and how to apply it in practice. So is it the editor/teacher’s fault when the students still don’t seem to “get” the lesson? Obviously, the writer/student has to want to learn from each edit of her content. Let’s face it – writers are typically not as dedicated to the style guide as the editor is. Often, the editor is the maintainer of the department style guide and therefore, has a particular familiarity with it and fondness for its sage guidance.

For the editor’s part, I suggest that your edit comments always point to chapter and verse in the style guide to support the change you’re requesting. That way, the suggestion is not so much coming from you, as from the textbook that you’ve all agreed to follow. If particular items in the style guide seem to be a constant challenge for one or more of your writers, consider offering a brief lunch-n-learn session to um, raise awareness on several points in the style guide. Another idea is to publish a style guide tip-of-the-week through email. Anything to reinforce your edits in a setting that is less personal.

That leads me to the other party in any edit, the author. As I said, the student has to be willing to learn from each edit. Perhaps the problem is not so much in whether the editor considers himself to be a teacher, but whether the writer considers each edit as an opportunity to learn and improve. We are all “set in our ways,” especially those of us who can boast a 20- or 30-year career in writing. But I’m baffled by scenarios like the following: 

  • I make a correction—say, about the difference in usage of “if” and “whether”—and provide the very clear explanation from Chicago Manual of Style. (I couldn’t offer an explanation myself; I just “know” when to use one or the other.)
  • Though the writer challenged my edit at first, the writer then acknowledges the correctness of my edit based on Chicago.
  • But the writer continues to make the same mistake in text and in speech.

The lesson wasn’t really learned. The behavior didn’t change. Sigh.

Did I mention that writers are not as dedicated to the style guide as the editor is? So this goes back to the part about the editor providing “repetitive reminders” in her teaching role. I guess that’s what you might call job security.

Eye for Editing: Do Not Edit …

Just because you can. Please, do not mark something for an author to change just to prove your superior knowledge of seldom-used symbols.

You think I’m kidding? Good, because you wouldn’t do something like this, would you? In the throes of final review to meet a draft document deadline, please don’t waste the author’s time—the author who is already stressed and has worked many overtime hours to meet the deadline—by demanding revisions that no one but you will notice. Resist the urge to point out every tiny flaw that presents itself.

Because it’s just not important.

If you recall the work-related scenario that I described in my last post (Eye for Editing: Caught Between Two Edits), this scenario takes editing comments to a new extreme. In a situation last week, among many other things the team lead mentioned during two days of group review sessions, she pointed out that I had used quotation marks instead of inch symbols when I brought content into the master document. I was expected to change them on the spot while she and my colleague watched. Excuse me? How is this minutia the least bit relevant at this point? It’s as if someone was trying to prove something.

Continue reading “Eye for Editing: Do Not Edit …”

Nine Steps to Improve Technical Editing Skills

Guest blog by Francis Bao, STC Chicago.

Technical writers always want their work to be recognized by the audience. Technical writing and editing skills are highly associated with each other. Effective editing will help make bad writing good and good writing becomes even better. Experienced editing will catch both factual and grammatical errors in copy before it is published, preventing  embarrassment, additional costs, and possible legal action. To become an experienced editor, here are some steps to improve your editing skills.

Step 1. Develop a mastery of the English language

It is very important for technical editors to learn and understand the basic rules of the language, such as sentence structure, grammar, and punctuation. Technical editors also need to develop advanced skills for editing the style and context of technical writing work.

Step 2. Know the purpose of the work you are editing

Technical editors need to define the goal of a writing work or the nature of its content in order to determine what kind of audience the writing is trying to focus on. Once the editors understand the purpose of the writing, they will be able to correct problems and help technical writers create sharp-looking documents.

Step 3. Familiarize yourself with the necessary style

Continue reading “Nine Steps to Improve Technical Editing Skills”