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

Hierarchical and sequential structures, especially popular since Gutenberg, are usually forced and artificial. Intertwingularity is not generally acknowledged—people keep pretending they can make things hierarchical, categorizable and sequential when they can't.

Ted Nelson



Navigation





<November 2018>
SMTWTFS
28293031123
45678910
11121314151617
18192021222324
2526272829301
2345678

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 - 11/16/2018

Totals
Posts - 2532
Comments - 2584
Hits - 2,096,862

Averages
Entries/day - 0.45
Comments/entry - 1.02
Hits/day - 373

Updated every 30 minutes. Last: 7:58 AM Pacific


  09:10 PM

During developmental editing, one of my jobs is to play user advocate and attempt, as best I can, to put myself in the reader's shoes (well, mind) while reading the content. In the vast majority of cases, the result is that I add questions or comments that boil down to "Need more info here."

This is a fairly natural thing for tech writing, I think. The writers tend to know their technology areas pretty well, and one of the most common problems you have when knowledgeable people write is that they find it hard to imagine what less-expert people don't know and hence what needs to be explicated. A colleague of once mine noted that it's important to "cultivate your naiveté" — certainly for editors — so as not to let one's personal expertise blind one to the reader's needs.

(A kind of amusing, tho ultimately tedious, reaction to my "Need more info" comments is for the writer to leave me a comment in reply that answers the questions. More times than I can tell you, I have copied the writer's careful explanation from a comment and just pasted it into the document proper right at the point where I asked the question.)

This user-advocate thing cuts both ways, tho. A problem I see sometimes is that a writer will over-explain things. I tend to see this under two circumstances. One is that the writer is comparatively inexperienced and gets caught up in a wave of unnecessary thoroughness.

I also see this sometimes when writers, including experienced ones, are dealing with new technologies and go on at some length because they are, in effect, recapitulating their learning experience. In both cases, the issue is that the writer is a bit unsure what the reader will know, and for which a natural impulse is to blather on. As I've become more experienced as an editor, I am more willing to say "Hey, I think the user doesn't need all this extra explanation."[1]

The trickiest situations are where the writer veers from one extreme to another in the same document. For example, I'm currently working on a tutorial for one of our technologies. It's not a 100-level piece; the 100-level tutorial is a prerequisite for this one. Let's call it a 121-level tutorial. So far in this tutorial I've encountered HTML5 markup, code in C#, complex types, and anonymous JavaScript functions. This is not beginner stuff; my editorial antennas quiver at some of this. If we just throw all these things at the reader, will we lose some of them along the way?

And then I'll run across some stuff that I think "Oh, c'mon, who is reading this doc and doesn't know how to do that?" For example, this tutorial contains explicit instructions for how to run the page in a browser, and then more instructions for how to view the page source.

I am allowed — obliged, in fact — to have opinions about what level the reader is at and what they might and might not understand. A writer might convince me that the reader knows enough (or conversely does not know enough) to justify a specific level of detail in a document. I'm a much harder sell, tho, for what I perceive to be mixing reader levels in the same document. And I do object pretty strenuously when I think we're whipsawing the reader. In the end, of course, it's the writer's call, but like to think that I can gauge the user pretty well.


[1] Not that this is inherently bad. Here's a thought from W. Richard Stevens that I like:

This process of digging up the details and learning how things work leads down many side streets and to many dead ends, but is fundamental (I think) to understanding something new. Many times in my books I have set out to write how something works, thinking I know how it works, only to write some test programs that lead me to things that I never knew. I try to convey some of these missteps in my books, as I think seeing the wrong solution to a problem (and understanding why it is wrong) is often as informative as seeing the correct solution.

However, this a different context from product documentation, where we try to get the user from question/problem to answer/solution via the shortest path possible and without exploring all the interesting side streets and dead ends.

[categories]   ,

|