Wednesday, December 6, 2017

“Perfect vs. Good Enough” – Writing Quality in the Online Age - Part 3


This is the last part of a three-part post looking at “perfection” in content creation in the online age. In this post, I’ll discuss the return of “perfection” but with a different meaning than it had historically and how that different meaning represents a sea change in technical writing.

In the old days, “perfection” was rarely defined but generally meant perfectly crafted writing. But perfectly crafted writing takes too long to create. Think about how often you heard a product manager say of the user guide “We don’t need it perfect. We just need it good enough and out there.”

The result was a tug-of-war within tech comm. One side claimed that the communication/writing side was what counted and the technical side was secondary. The other side took the opposite position. Those in the middle, like me, claimed that both were important. Communication was our business but without the technology, there was no way to share that communication with readers.

So how has the meaning of “perfection” changed?

In the old days, the code behind the content didn’t matter as long as the document printed correctly. The result was documents full of syntactically incorrect or junk code. But today, we have to assume that any content we write may be converted between formats and presented in some online form. Plus, the rapid pace of modern publishing means that problems that require manual intervention to correct are bad. This change is driving a new requirement for “perfection” but on the technical side. How?

·         Syntactic correctness is crucial to using conversion tools to move content between formats. No more hacks or Easter eggs. This means any old tools that aren’t syntactically correct will have to be abandoned, no matter how invested your company may be in them.

For example, a few years ago, I did some work for a company that used an HTML editor that was created around 1999 and that followed acceptable syntax as it existed in 1999. Unfortunately, that syntax didn’t work today. For example, it denoted heads not by the standard h1, h2, etc. tags but by span tags with class numbers. This worked as long as the company used that old tool. But that old tool was limited. In order to go beyond its capabilities, the company had to first correct the code. Doing so would require using Regex but the company didn’t want to spend the money. Checkmate.

·         Good coding practice is crucial to taking advantage of responsive design.

For example, if there’s a problem aligning three images horizontally, common practice is to insert a table on the page, hide the cell borders, and insert the images in consecutive cells. This works well until users view the page on a mobile device. Now, rather than shifting automatically from a horizontal layout to vertical, the images remain horizontal and users have to scroll horizontally. Horizontal scrolling isn’t the end of the world but it doesn’t take advantage of the capabilities of responsive design.

·         Good SEO (search engine optimization) practice is crucial for effective searching. As more and more content goes online, you want your content to show up at the top of the search hits list and SEO will help. Of course, all your competitors are thinking the same thing…

·         Good metadata and taxonomy practice is crucial for machine-driven assembly of small chunks of content – Information 4.0’s “molecular content” or “granular content” – into output quickly to respond to user requests in transitory contexts.

·         Cross-platform-appropriate linking is crucial for usability.

For example, authors often use popups for online help to display small bits of content and, more important, to keep users within the topic and task thread. (Using jump links lets users get out of the topic and thread and perhaps lose their train of thought.) However, if you’re creating online help that’s responsive for use on desktop screens and mobile devices, be aware that popups will render as jumps on mobile devices, harming your navigational design on mobile devices.

·         Accurate linking is crucial for content credibility. Broken links happen but they can make users question the quality of the content and thus its credibility. And because the same content may appear on multiple devices, possibly on multiple network nodes, the risk of broken links goes up.

·         Future-proofing research is important to understand emerging platforms or technologies and to consider their effect on your content authoring.

For example, chatbots have suddenly become hot. I think it will be years before most companies create them but things can change unexpectedly.

      What about on the writing side? Is good writing still important? Yes, in a way.

·         Accuracy is obviously always important.

·         Good, consistent style is important, expressed through devices like parallelism, to support retention.

·         Good, consistent tone is important, expressed through devices like using active voice for the second person – e.g. “you”.

·         Good punctuation is important sometimes.

For example, the obsession over the number of spaces to use after a period seems silly to people who aren’t in tech comm (and to many who are). Other punctuation issues may seem just as silly until you point out the problems they can cause. (One programmer in a class that I taught said that punctuation rules were “a load of crap”. I pointed out that coding has its own punctuation rules and that breaking them might cause a program to crash. I then suggested that he consider the difference between “Let’s eat, grandma.” and “Let’s eat grandma.” He agreed and made it up to me by telling me what he claimed was the world’s worst accordion joke.)

·         What’s less important is creative perfection, le mot juste. We don’t have time for it and most readers won’t appreciate it anyway.


So “perfection” is a requirement again in tech comm, except that the word now has a different meaning. It still matters on the communication/writing side but is crucial on the technical side and represents the continuing ascendancy of that side of tech comm.