1. Original Entry + Comments2. Write a Comment3. Preview Comment


February 21, 2023  |  "Sparkle" edits  |  1506 hit(s)

Not long ago I had lunch with one of our technical writers, and she shared some thoughts about what she referred to as “sparkle” edits. We agreed (I believe) that technical documents benefit from developmental edits to help the writer with organization, purpose, and audience. We also agreed that it’s good to get edits for clarity.

But in her view, there was a point of diminishing returns for editing. It’s certainly possible to comb through a document and make sure that every sentence conforms exactly to our style guide. We can scrutinize the text and see how many words we can squeeze out. We can go back over the text again to make sure that every instance of passive voice is justifiable.

The problem is that this level of editorial scrutiny takes time and effort. And not just the editor’s effort; many such edits have to be discussed with the author to make sure (for example) that the meaning isn’t altered.

Is it worthwhile to do all this work to make the doc “sparkle”? The writer observed the following:

We need to get documentation out in a timely fashion. A few days or a week spent polishing up the prose is a few days’ or a week’s delay in getting the text in front of users. It’s also a few days or a week that the writer and editor aren’t working on other text that’s also important. (See also Editing and “meatball surgery.”)

We know that our readers don’t read every word in our documentation (or anyone else’s). Readers have a problem, they search, they skim, and they read only as much as they need to solve (or think they’ve solved) their problem. The Nielsen-Norman Group estimates that people probably read between 20% and 30% of text on a web page. It’s more important to make sure that text is scannable than it is to worry about some infelicitous text here and there.

Much of our documentation has a relatively short lifetime. A tutorial or whitepaper we’re working on right now might be superseded in a year or two. How much additional work do we want to put into something that will have few readers in 18 months?

As I’ve noted before, one of my early writing leads liked to remind us that “We’re not writing literature here!”

In our defense, so to speak, there are some editorial issues that don’t appear to have direct benefit to the writer or to (some) readers. A percentage of our text-focused edits pertain to making text accessible or more inclusive. Some of what we work on helps our global audience and makes text easier to translate.

And I’ll concede that some of these types of edits do indeed look like “sparkle” edits—they don’t seem to make much difference from the writer’s perspective. But as noted, they help in less obvious ways.

Still, I understood the writer’s frustration with “sparkle” edits. However we might define these, the larger issue is that when editing becomes friction in the process, writers start to get frustrated. If they have customers waiting for a document, and if they’re not seeing the benefits of the edits that they have to review, they become unhappy with the whole editorial process. We see this indirectly in that some of our engineer-writers occasionally choose to bypass our process and publish on Medium or some other more blog-like (and more direct) outlet.

It's important for technical editors to realize that they’re part of a larger effort to get information out to users. Of course we want to give the reader the best possible text. But we have to be very careful about spending time on edits that go beyond helping the reader and that become more about editor-facing concerns (“but that’s what it says in the style guide!”). When we’re standing in the path between the writer and the reader, we want to be very sure that the time and effort that we’re putting forth—and asking the writer to put forth—are really worth it.





Diane Olsen   22 Feb 23 - 5:48 PM

Thank you for writing this post about our recent lunch conversation! I've been meaning to write something on the subject myself, but I never seem to get around to it. I do agree with you on the value of developmental editing, accessibility and inclusiveness, etc. And I've spent plenty of time explaining to other writers(!) as well as engineers what a style guide is and why it's important. That said, I really hope editors take your post to heart. True sparkle editing - polishing a document that adheres to the style guide and meets or exceeds any reasonable quality bar - is at best a waste of time. At worst it's an existential threat to the technical editing role in an industry that isn't entirely sold on the value of that role.