Phrasing

Nearly a decade ago I was given a wonderful opportunity to learn on-the-(volunteer)-job about technical writing with The Linux Documentation Project. Tille had some excellent tips on how to make documentation more readable for people working in a second (or fifth) language. The tip I remember best is:

When describing an object, list the generic bits first.

Compare these two examples:

  • Upload your theme’s folder to the directory sites/all/themes.
  • Upload your theme to the sites/all/themes directory on your server.

After nearly a decade of flipping my sentences and adding generic words, the second sentence seems incomplete to me. I know my editors hate it, but I also know it makes the language more accessible to a wider audience.

Fast forward to today. I’m now working on a series of instructional videos. In the videos I have to speak out the instructions of what to do. I find myself stumbling over the phrasing, as my brain decides between the more “natural” terse phrasing and the way I would write out the instructions.

I’m sure there’s a sweet spot for narrated videos; and I’m sure everyone has their own style…if you create instructional videos, do you have a conscious preference of how you phrase sequenced steps? I’d love to know how you chose what works best for you (and your audience).