About

I'm Mike Pope. I live in the Seattle area. I've been a technical writer and editor for over 30 years. I'm interested in software, language, music, movies, books, motorcycles, travel, and ... well, lots of stuff.

Read more ...

Blog Search


(Supports AND)

Google Ads

Feed

Subscribe to the RSS feed for this blog.

See this post for info on full versus truncated feeds.

Quote

The whole integrity of editing rests on the editor's ability, when challenged, to give a reasonable and persuasive explanation for every change in the text — and that disagreements over judgments can be worked out collegially, in discussion.

John McIntyre



Navigation





<June 2018>
SMTWTFS
272829303112
3456789
10111213141516
17181920212223
24252627282930
1234567

Categories

  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  

Contact

Email me

Blog Statistics

Dates
First entry - 6/27/2003
Most recent entry - 6/15/2018

Totals
Posts - 2502
Comments - 2574
Hits - 2,056,522

Averages
Entries/day - 0.46
Comments/entry - 1.03
Hits/day - 376

Updated every 30 minutes. Last: 9:13 AM Pacific


  09:02 AM

Imagine that you're a music company in about 1984. For many decades you've been selling vinyl records, and then along comes this newfangled "compact disc" business. It's obvious to your company that this is the future, and your audiophile customers are all excited. But your everyday customers are confused: are you going to stop making records? Are they supposed to replace their enormous record collections with CDs? And what about the whole ecosystem that's grown up around records: record stores, stereo manufacturers, even furniture makers ... what do you tell them?

I've lived through similar scenarios in the software industry multiple times: the company devises a new technology—not just an update to your already successful releases, but a new approach. As with the record company, tho, it's rarely easy to simply pull the plug on your old stuff, since many of your customers are heavily invested in your old technology.

If you're the documentation person under these circumstances, you have a tricky job. If the new technology is sufficiently different, you can create a brand-new documentation set from scratch for the new technology. (The documentation sets for record players and CD players have very little shared information.)

But it's not always that clean a break. Consider a database product where the new technology is an innovative search syntax. Everything else about the database (storage, backup, etc.) is the same; you just have a new way for users to craft their queries. Moreover, the old query syntax still works.

Too often, what ends up happening is that writers add a section to the existing documentation that describes the new technology. This "solves" the problem. Hey, now we have two technologies! We've documented both of them!

But what do your users actually need?
  • All users need to understand that there are two technologies, and why, and how users should choose between them. In your compare-n-contrast, you have to be careful not to trash-talk your old technology (in spite of what your engineers and early adopters probably think); a few years ago, you spent a lot of effort to convince your users how great that technology was.

  • Existing users need to understand what the new technology means for them. Do they have to upgrade? What does it mean for their existing investment? How long can they continue to use the old technology?

  • New users (probably) need to be directed to the new technology. They also need to understand that there's an existing body of knowledge about the old technology (for example, documentation and articles and books and forums) that could mislead them if they're not aware of the different versions.
You can accomplish this easily—well, "easily"—in some sort of introduction or overview. But you also have to think about how to help users who drop into your documentation from unexpected places—say, from a web search. Your existing documentation is of course all about the old technology. The descriptions are about the old stuff; if there are examples or illustrations, they're probably about the old stuff. Existing customers will probably continue to use the old technology and will still need documentation for it, so you can't just rip out the old stuff and replace it with new docs.

You might consider reviewing every page of your existing documentation where the old technology is featured (for example, every page that shows query syntax). Then you have to ask whether you replace the existing examples with new ones, or whether you add corresponding examples of the new syntax. In the latter case, how much explanation do you need in order to make sure readers understand that there are two syntaxes?

As I say, I've lived through this. As of last year, the technology I worked with (ASP.NET) had three distinct approaches to creating websites. We had a heck of a time even crafting the message of how to select between them.

And the idea of visiting each page (page design, database access, deployment, etc.) and updating it for all three technologies—or creating technology-specific versions of each of these stories—was a challenge indeed. (They've since added a fourth technology fourth and fifth technologies.)

The evolution of a product is of course exciting for users, who get new and improved technology to work with. But unless a new technology represents a completely clean break with the old, and unless you can create separate, standalone doc sets for each technology, in some ways the documenter's job can actually be harder than it is for the engineers.

[categories]   ,

|