The Slow Word movement for technical documentation?

Would a “Slow Word” movement be useful for technical writers? Hmm. Lots of argy-bargy potential here. I’m just going to write up some musings. You’re sure to have some thoughts too. Drop a comment. Slowly, take your time...😉

Trevor Butterworth has written an article at Forbes.com entitled “Time For A Slow-Word Movement”. He’s referring to media publishing in general, rather than technical documentation in particular. He points out the fast-moving, internet-savvy, click-it-and-go world our readers live in, and says that it’s affecting their ability to read and enjoy published works. He suggests a “Slow-Word movement”, comparable to Slow Food.

I love the way Trevor uses language to illustrate and embody his thesis. Reviewers and commenters have called his language “curmudgeonly”, “baroque” and “grandiloquent”. Yes, but that’s the point! I don’t agree with all of what Trevor says, but his article sure got me thinking.

How much of what he says can we apply to technical documentation? Would we, and our readers, benefit from slowing down, smelling the daisies, writing good manuals and reading the manuals? BTW, Tom Johnson says it’s OK if no-one reads the manual.😉

The whole world’s gotta slow down. Or not.

Trevor writes about his idea of a Slow Word movement,

“The idea of consuming less, but better, media–of a “slow word” or “slow media” movement–is a strategy journalism should adopt.”

He emphasises the (lost) pleasure of reading. I think it’s our duty and our calling, as technical writers, to provide user assistance that is a pleasure to read. Or watch, hear, consume in the way the reader prefers.

So, we should all slow down. But isn’t the whole point that people need to read stuff fast these days? The readers of today skim our documents, web pages and blog posts. I do it all the time. Trevor says, “In short, a relentless, endless free diet of fast media is bad for your brain.” No, I don’t think so. That’s a generalisation. But I do think we need to fight for our place in the multi-tasked, information-overloaded brain that is our reader.

Quick, grab that reader

I’d like to highlight an aspect of the “Slow Word” message: We don’t want to write slow words. Rather, we need to write words (or whatever) that slow our readers down!

(From now on I’m going to refer to “documentation” and “words”, but I’m encompassing all the various media we use. Instead of just the written page, we can use online help, videos, audio, e-learning – whatever form our readers need.)

We need to slow people down just long enough to get our information across. Otherwise, people will rebound off our page, hit Google, ricochet aimlessly around the intertubes and then give up, frustrated and testy, and apply a second-best workaround or buy a competitor’s product.

How do we clamp our readers down? Ah, there’s the rub. That’s where our training, skill, enthusiasm and creative skill come into it. I think it’s nothing too scary, but rather a realignment of what we’re already striving to do:

  • Keep our documentation concise. This takes time, re-writing, crafting and review. That’s where “slow” comes into it. The Slow Word movement is all behind the scenes.
  • Present our content with flair. It must be a pleasure to read, watch, hear.
  • Add a surprise here and there. Haydn dude, you rock. I don’t think it does any harm to let a touch of personality, a delight, a giggle creep into our documentation. Here I’m talking about the sort of technical documentation most of us are doing, predominantly in the information technology world. There are obviously documents where levity would go amiss.
  • Know our audience. People of very varied levels of expertise come across our documentation via the web and various media. If we had the time and resources, it would be awesome to write a documentation suite targeted to each level of expertise and each medium. Since we seldom if ever have that luxury, maybe the best way is to create short, discrete documents. Like building blocks that people can choose and build on as they need them. The skill lies in chunking the information right and in making the building blocks easy to find.
  • Focus on the purpose of the document. We’re often asked to include all sorts of dross on our pages, such as legal messages, product advertisements and cross-selling blurb. These will tire and distract our readers, who are already battling the stream of tweets, RSS news items, IMs and email popups flaring up all over the planet. Our content must be king.
  • Grab the reader’s attention where it’s at. I’m going to escape from this bulleted list now, because I have a fair bit to write about this one.

Grab their attention where it’s at

The Slow Food movement aims to “counteract fast food and fast life, the disappearance of local food traditions and people’s dwindling interest in the food they eat”.

Instead of counteracting the fast peppy media world our readers inhabit, I’m thinking we should jump in boots and all, kick the borders outwards and put our content in the middle. Up with technical documentation, in whatever form it takes. Build on the old traditions, ride the new ones and create our own. And we’re doing that! Technical writers are experimenting with Twitter, video, wikis, structured authoring, collaboration and feedback mechanisms, you name it.

A glass of wine and something to believe in

The Slow Word movement for technical documentationThe Slow Food movement aims to “bring together pleasure and responsibility, and make them inseparable.” Yes, that works for the documentation too.

Going back to Trevor’s Slow Word movement: Our readers need “something to believe in rather than rail against, something elegantly simple and bipartisan that has sufficient aesthetic compulsion to sound pleasurable rather than penitential”.

OK Trevor, you gotta admit, that’s a trifle long-winded.😉 But yes, the message applies to technical documentation too. We want content that is clear, concise, correct, attractive. Not a pain to read. For sure, “it’s simply unrealistic to expect the public to read [manuals] as a daily personal moral commitment to [documentation]”.

A glass of wine as the “kind of social media that really works for business and play”? Awesome. Thank you Trevor for a thought-provoking article.

Happy New Year, everyone!

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 1 January 2010, in technical writing and tagged , , , . Bookmark the permalink. 14 Comments.

  1. Oh, the writer in me wants so much to agree with you, Sarah. But alas….Much as I love a good glass of wine, if I’m running in a road race I just want a cup of water that I can gulp down and toss aside.

    I read for (at least) two different reasons: (1) To hear a good story or expose myself to new ideas; and (2) To get information I need to complete a task, like filling in a tax form or installing a software update.

    “Slow words” are great in the first case — in a novel, an essay, an opinion article.

    But when I’m trying to complete a task, I want to see a bulleted list or a table where I can skim through and quickly grab what I need. If it’s necessary for me to understand some conceptual information, I want it to be as concise as possible. In this case I would resent it bitterly if a writer tried to slow me down.

    One of your bullet points sums it up perfectly: Focus on the purpose of the document.

    • Hallo Larry

      Great comment! You’re so right about the different reasons for reading. Heh, and I guess I’d resent it too if the writer tried to slow me down!

      Maybe we need to be so very skilful that the readers are oblivious to our attention-hooking techniques and unaware of the time we’ve spent getting the information into just the right form. If they find better, and faster, information somewhere else, that probably means our documentation is not well crafted.

      I don’t really think a “Slow Word” movement is an idea that will fly. But it’s got a definite “something”. Maybe it’s just the catchy name. Food for thought at least. Slow or fast.😉

      Cheers, Sarah

  2. Sarah,
    I love that you’ve tackled (or detained in a leisurely manner?) this issue.

    But is this triangular comparison a false syllogism? Slow (sensually experienced) food -> slow (sensually, artistically, and intellectually enjoyed) prose -> slow (“ordered,” creating an experience that controls [!] the reader) documentation?

    Isn’t our job to empower a user (i.e, give him/her tools to create his/her own experience) as intelligently, efficiently, and quickly as we can? Isn’t our strength that we understand how to use words as informational launches and landings rather than as frightening cliffs?

    …My soapbox, here: Good help/documentation is the opposite of argumentation: It provides many logical and intuitive jumping-on places and many well-conceived jumping-off places, and it doesn’t constrain the reader (note: no longer a “user”) to a particular experience or conclusion – which (at least I think-pls correct me) is the nugget of this eight-course slow word documentation idea.

    There’s a poster in the hallway of our office that says, “It’s not what the software does; it’s what the user does.” In other words, let’s not assume user function should follow our desired form.

    -Just my 2c.

    • Hallo Jenny

      Yes, I think you’re right! The Slow Word concept is intrinsically flawed. We do want to hang on to our readers, but only because we have good information to give them and because they realise instantly that they’re in the right place. How do they know? Because of the elegance and just-plain-rightness of our docs.

      So the “slowness” is all behind the scenes. It takes a long time to produce documentation of such elegance.

      Or not… Bring on the nay-sayers.

      Cheers
      Sarah

  3. Love this post, Sarah; thanks for drawing my attention to the Forbes article. Must mull this over, over a glass of wine!

  4. It’s hard for me to know what my audience is doing, because I never see them, and I never get feedback on my documentation. However, I expect they use if very lightly. They get in and get out. I doubt they even read the introductory paragraphs in the procedures. They probably just run a search, find the title that looks like the instructions they want, and start running through the procedural steps.

    About a year ago, I started what you could call a “slow word” project. It was an attempt to explain how my company’s product (which is computer communications software over multicast networks) using common associations. The goal was to explain the entire concept from the ground up using analogies that most people could easily understand.

    About halfway through the project, I came to a realization – that this wasn’t going to do any good because my audience already knew everything I was telling them. It would only serve to educate those who were starting from the ground up, and that wasn’t who I was really writing it for. So while it was fun, and snarky, and easy to understand, it served no purpose and no one would ever be interested in reading it except for in a VERY small niche (like maybe a community college course or something).

    In the end, I’ve come to believe that writing long fun to read manuals for things is best done for general subjects that target a large audience. For instance, if I were writing a how-to manual for an entire computer language, then yes, because the audience is large and there’s plenty of room to have fun and make analogies and get the info across. But for something small and specific – most people don’t want to read a novel about it or be entertained as they learn. They just want to find what they need to fix the problem so that they can get on with their jobs and do something else.

    I focus on letting them do that.

    • This is a really interesting comment! I love your story about starting a long and clever write-up and then abandoning it on realising that no/one is ever going to read it. Been there done that.🙂 It’s part of a tech writer’s job to recognise these occasions.

      On the other hand, it comes back to the purpose of the document. Perhaps it even comes down to the purpose of part of the document. Because, as you pointed out, we often don’t know why the reader is reading our document, especially if it’s online and they surfed in via Google.

      Structured writing has some advantages here. For example, DITA’s division of topics into task, concept and reference types. The reader just may have come to our docs because they need to understand the nitty gritty of a concept.

      In our documents we make sure the procedural bits are easy to find, via a coloured panel and stem sentence. But the conceptual and reference info are there too.

      • DITA is something I need to learn more about.

        I love writing long fun to read documents, but it’s just not correct for my current product line. Previously, (in other companies) when I’ve documented game development software, then I had more leeway and took advantage of it. I also did a programming language where I could throw in some fun. Jobs like that are great, but they’re hard to come by. In my experience, (15 years tech writing now) most of the material needs to be professional, clean, and somewhat boring. That’s what the client asks for, and they’re handing it off to their bosses as well. I’ve done business process manuals where that was the rule. Just the facts Ma’am. But what those documents really needed was something to break up the monotony and make them fun to read.

        Maybe someday there will be a writer’s revolution, and we’ll all start throwing snarky prose into our manuals. Power to the people!
        🙂

      • Oh, man–I would give my right arm right now (I’m a lefty) to get some DITA in my wiki sitch. [Sniffs, thinks back fondly to structured Frame.]

      • DITA rather than wiki? Oh nooooo!😉

  5. “The Clinton-Lewinsky scandal had revealed a news media publishing at “warp speed,” discarding probity for prurience and embracing a non-stop news cycle of aggression, allegation and assertion where once facts were checked and sources confirmed before ministering scandal to the public.”

    Cannot agree more. Excellent statement on today’s journalism, especially the electronic media.

  6. Enjoyed the post, Sarah. I was thinking about what you’ve said and thought that error messages would be a good way to “grab the reader”. Many users instersect with documentation when there’s a problem.

    Error messages are often overly terse, unhelpful and dry. “Slow word” can help there with a better (yet concise) description of the problem with a link to the help documentation.

    This approach requires a lot of co-operation between developers and tech writers, but would help users tremendously. We just started doing this and I’m pleased with the results and hope to do more of this.

    And there could be room for a little personality in these error messages too. I see these in Twitter, “Oops” or “Forgot your password? I happens to the best of us. Here’s a link”.

    • Hallo Patti

      What an awesome perspective! It’s a great idea to direct the readers to the documentation via error messages. As you say, we’d need to work closely with the developers. Always fun. 😉

      We will also need some procedures or cross-checking, to make sure we don’t delete a page that an error message points to. If the page title is part of the URL then we need to control changes to the title too. But these procedures are necessary for any context-sensitive help.

      I love the idea of a quirky error message appearing every now and then. Just a few days ago, Firefox gave me a message something like this:
      “Well, this is embarrassing. Firefox is having trouble restoring your session…”

      My reactions, in quick succession, were: What? LOL! Ah well, no worries, I can find my sessions again.
      So the funny message diluted my frustration and prevented any annoyance with the product.

      Following on from the funny words, Firefox also gave me information on possible causes of the problem and how I could resolve it. I didn’t really read those. Typical user!

      Thanks for a great comment.
      Cheers, Sarah

  7. I write not slow..

    In my community, must learn blogger 5 minutes write article. Just for have fun, but good thought. Because, make me flow like snow ball when I write.

    Happy New Year Too.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: