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

Once a group gets large, it has to dumb down. We know this with regard to corporations. Same rules apply to religions.

Paul Denlinger



Navigation





<December 2018>
SMTWTFS
2526272829301
2345678
9101112131415
16171819202122
23242526272829
303112345

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 - 12/14/2018

Totals
Posts - 2538
Comments - 2589
Hits - 2,103,048

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

Updated every 30 minutes. Last: 11:08 PM Pacific


  03:00 PM

In the latest A.Word.A.Day AWADMAil roundup of user comments, someone linked to the Web site of Robert Lang, an origami master. And I do mean "master"; go have a look at what the guy has done, omg.

The guy obviously thinks Deep Thoughts about origami. One of the items on his Web site is an article he wrote not about how to create specific origami figures, but about how to write instructions ("diagramming") for origami figures. I don't know why exactly I glanced through this, but I did, and as I read it, I realized that almost all the conventions he proposes are equally applicable to our work, or at least the part of it that concerns step-by-step instructions. In fact, his advice is probably generic to any procedural documentation.

Herewith some of his proposals:
  • Be consistent with the past. The takeaway here is to respect what readers already know; don't make up some new conventions that they'll have to learn in order to understand your instructions.

  • Be grammatically correct. By which he means that you should use words consistently; the same elements are always described the same way.

  • Make the drawings/text stand alone. What if your reader can't see the diagrams, for instance? A picture is worth a thousand words, but you probably still need to write those thousand words.

  • Don't leave the reader dangling. I'll just quote Lang, because he says it just fine: "One of the greatest cruelties a diagrammer can perpetrate upon the reader is illustrated by the following scenario. In step 113, we are instructed to perform an exceedingly complicated series of closed sinks and to turn the paper over. Step 114, therefore, shows the opposite side of the model. The paper does not get turned back over until step 243, at which point we discover we folded step 113 all wrong, but it’s too late now. Always show the result of any procedure immediately."

  • Show one step per drawing. This rule is surprisingly hard for people to follow, in my experience.

  • Distort the model for clarity. His example pertains to how a drawing can be more useful precisely when it isn't exactly what the user sees. In our world, this generally means simplifying the scenario to remove information that would be extraneous or distracting at that point. I discussed a couple such simplifications earlier; another example is that we filter out aesthetics -- fonts, colors, etc. -- unless they're germane to the task at hand.
I've left a couple out as more specific to origami or illustration, but overall, his advice resounds quite well with me.

[categories]   ,

[1] |