Reality check: Writing for scannability and localization

Writing documentation for usability and scannability has several effects, as I’ve recently found out.  After recapping some principles, I share some anecdotal feedback on scannable documentation I’ve written.

Writing scannable documentation

[These principles first appeared in my recent post “Do you know Time?”]

Documentation can be more successful when we make it easy on our users to use and apply it quickly:

• Clear topic structure helps users to orient themselves and learn the lay of the land quickly
  • Separate topics by type, whether it’s concept, task or reference.
  • Keep self-contained topics short and concise.
  • Insert indicative links to related topics.
  • Imply the topic type in the heading:
    • Nouns lead in headings of concepts
    • Imperatives lead in headings of tasks
    • Names of commands, variables, etc. lead in headings of reference topics
• Parallelism (giving sentences of similar purpose a similar structure) improves scannability, comprehension and retention.
  • Start each mandatory step in a procedure with an imperative verb.
  • Start each optional step with “Optionally”, followed by an imperative.
  • Front-load your sentences, so the beginning of a paragraph indicates what the paragraph is about.

Reality check

I’ve recently written a user manual that applies these principles. It’s a guide for implementors to set up and configure a complex, customizable workflow of about two dozen steps. In that workflow, users can first import data from several sources, then validate the data, then process it, inspect and validate the results and create reports. So I have about two dozen sections that outline how to configure each step and how to test the configuration.

Here’s some of the feedback I’ve gotten on that manual – and my comments:

The documentation is quicker to navigate and easier to read.

Thanks – that was my intention, and I’m glad that it seems to work. 🙂

All those links to related topics are giving me the run-around. I want to know how to do stuff, not turn pages back and forth!

This is a reaction to topic-based writing, and I would think it fades away once users have gotten used to self-contained topics. There is actually an advantage to this: Users may leaf around a little more at first, but overall, they’ll spend less time searching and more time finding because it’s clearer what can be found elsewhere and what can’t.

I think this makes users more confident, too: If something is missing, they can move on to other means of support quickly. It’s bad enough if the documentation is possibly incomplete, but it’s worse if users get frustrated not knowing whether information is missing or somewhere else. (That last situation sounds like Donald Rumsfeld’s “unknown unknowns”…)

The structure makes the instructions repetitive and boring.

True enough, that’s the downside. What’s easy to grasp when reading one or two topics becomes boring when you read the complete manual.

The best answer I can offer is that I’d rather be clear and concise than self-servingly funny. (Or should documentation add fun to what is essentially an arduous setup process in a professional piece of software?)

The headings look weird when translated.

Ah, yes, good point! On the one hand, the translation is neither less nor more formulaic than the original manual. On the other hand, it does look weird when the translation focuses more on conventions of the target language than on scannability.

German is about as big on nouns as English is on verbs. So an English imperative in a heading “Configure the data import step” easily becomes a noun in German: “Konfiguration des Schrittes Datenimport”. (And I do need the “step” in there to distinguish it from the non-workflow “task” – it’s an intricate system…) Imagine several parallel entries “Konfiguration des Schrittes…” in the table of contents, and you have repetitive boredom alright.

However, you can also “front-load” such headings: Write “Datenimport-Schritt konfigurieren”, and the scannable unique part comes first. Writing for scannability benefits when translators know the applied principles…

Your turn

What’s your experience? Does writing for scannability work? Do users appreciate it? What issues have you encountered when localizing structured or fomulaic writing?

Advertisement

The dangers of PowerPoint

Every time you make a PowerPoint, Edward Tufte kills a kitten. – Mark Goetz

I picked this up as a ‘re-re-re-tweet’, and the original sleeper post from last November called “My new wallpaper” has a cool wallpaper design worthy to go onto a geeky t-shirt!

Oh, and here’s a blog post “Dilbert on PowerPoint Presentations” which collects 24 strips on the topic.

Does change management work for doc teams?

We technical writers are frequently very good with tackling new subjects – but not so much with tackling new processes. That sounds paradox, but it’s quite understandable: The reason we’re so good and flexible about what we describe is often that we’ve refined how we describe it. So changing how we write is a challenge, for writers  – and their managers, too, as Scriptorium’s Alan Pringle points out:

Without good management, the implementation of new processes will likely fail. (I’ve seen bad management kill an implementation, and it’s ugly.)

So how can you employ change management to improve and advance the way tech writers work? Alan explains three specific action points that are especially valuable when you’re moving to an XML-based model, but I’m looking for a more comprehensive angle…

Enter John Kotter

So I turn to John Kotter, who wrote a standard book on change management, Leading Change. Here’s a PDF with the gist of Kotter’s ideas in 7 pages. He lists common errors that impede organizational change  and maps them to a sequence of an “Eight-Stage Process of Creating Major Change”. It addresses problems that are probably familiar to writers and managers:

• Establishing a sense of urgency to overcome complacency
• Creating a sufficiently powerful guiding coalition
• Generating short-term wins
• Anchoring changes firmly in the corporate culture

I think these are good general management tools. But do they work for documentation departments? I find that Kotter’s recipe is frequently undermined by the low profile that documentation often has: I can make a good case that documentation is important and often undervalued. But frequently, its quality and scope are not seen as mission-critical for the success of a product or its manufacturer. Then how do you establish a sense of urgency strong enough that “most managers honestly believe that the status quo [in documentation] is unacceptable” (Kotter, p. 48), so a guiding coalition can be created and sustained?

Managing change with writers

So I try Richard Hamilton’s Managing Writers, one of the very few books about, well – you’ve read the title. Hamilton sounds a bit wary of Kotter’s idea to create a sense of urgency. He calls it the “burning platform” (p. 64f.) which will only stir people into changing if the platform is real and the writers are actually on it. Instead, he suggests Pip Coburn’s The Change Function from which he quotes:

Users will change their habits when the pain of their current situation is greater than their perceived pain of adopting a possible situation. (Hamilton, p. 63)

That sounds reasonable and more tangible, more on the level of writers who ultimately do the changing or not. The danger here is to give in to the evil you know, so you can avoid the evil you don’t know. Also, major change in documentation teams will often require migrating legacy contents or rewriting it, and either one adds tremendously to the perceived pain of the solution which impedes change.

Your turn

What are your experiences with change management in documentation? Do Kotter’s top-down ideas work? Can you give Coburn’s idea the right spin, so the perception leans toward change?

Does structured writing stifle creativity?

I hear that a lot, but I don’t think that structured writing limits creativity. Look at poetry, look at sonnets. That’s about the most regulated, structured writing you can get – and yet nobody thinks poets are not creative.

Today’s quote of the day is a paraphrase from one of the speakers at last year’s DocTrain West, but I can’t remember who. (If you remember saying this, I’ll be glad to credit you… 🙂 )

The idea stuck with me, because I think it’s a very apt comparison. Just as sonnets impose a certain number of lines and a choice of rhyme schemes, structured writing allows you to mix and match elements in topic types. It redirects the creative challenge to focus on contents.

As Sarah O’Keefe points out in her recent article “XML: The Death of Creativity in Technical Writing?“:

XML kills off the possibility of creativity in one specific area (formatting)… Technical communicators add the most value and have the most opportunity for creativity in crafting sentences, paragraphs, topics, and groups of topics that explain complex concepts to their readers. XML does not interfere with this mission.

What do you think? Does structured writing interfere with your creative impulses?

Do you know Time?

We know what IT is and we know TIME and we know that everything is really FINE.

… says Dean Moriarty/Neal Cassady in Jack Kerouac’s On the Road (part 3, ch. 5). Now, Neal was known for a lot of things, but tech writing wasn’t one of them. Still, I believe we writers, too, can know time, so I’ll look at different aspects of time and how they affect the success of our documentation.

Time to produce
This one is obvious: There’s the time to write and produce our deliverables until we have to get them out the door, when the deadline approaches or the money runs out.

Time to consume
Whether our documentation is successful also depends on how much time our users need to find, read and apply it. I’ve seen help where I couldn’t find answers and manuals where I couldn’t tell if a poorly structured 20-page chapter would actually be helpful.

This is when users turn to search engines and forums instead of documentation. As Scott Abel points out: “Users don’t care where they get help from – they just want to find the answer to their problem when they encounter it”, and if it’s from another user at 2:30 a.m.

Knowing time
Users don’t only want help “now”, they also need to know time – literally, as I’ve learned from two incidents last week:

I was watching a documentation screencast with excellent contents. But the Flash player had only a general progress bar, with no indication of remaining time and poor navigation within the playing film. I found it so distracting, I would’ve gladly traded in the benefit of seeing the action on the screen for better orientation and pacing on the written page. Knowing time helps to orient users to where they are.

Then I went to a Pecha Kucha night – and the place was packed. It sounds like a strange concept: Would you go and see a dozen or so PowerPoint presentations on topics you didn’t know in advance by artists and designers you probably not know? Loads of people do – because each presentation is 20 slides for 20 seconds each. 6:40 minutes, and it’s over. You spot a bad one in the first 10 seconds? You take a leak, get another beer and are back in time for the next one… The same idea makes the 22-minute meeting so intriguing. Knowing time helps to focus attention.

Writing for time
So I believe our documentation can be more successful when we make it easy on our users to use and apply it quickly. And there’s a lot we can do towards that end:

• Clear topic structure helps users to orient themselves and learn the lay of the land quickly.
  • Separate topics by type, whether it’s concept, task or reference.
  • Keep self-contained topics short and concise.
  • Insert indicative links to related topics.
  • Imply the topic type in the heading:
    • Nouns lead in headings of concepts
    • Imperatives lead in headings of tasks
    • Names of commands, variables, etc. lead in headings of reference topics
• Parallelism (giving sentences of similar purpose a similar structure) improves scannability, comprehension and retention.
  • Start each mandatory step in a procedure with an imperative verb.
  • Start each optional step with “Optionally”, followed by an imperative.
  • Front-load your sentences, so the beginning of a paragraph indicates what the paragraph is about.
• Minimalism trusts users to figure out some stuff on their own (quotes from John M. Carroll’s The Nurnberg Funnel)
  • Address users with realistic task topics
  • “Help users get started fast”
  • “Rely on the user to think and improvise”

But beware…
… and heed Henry David Thoreau, who gives better advice to writers than Neal Cassady:

Not that the story need be long, but it will take a long while to make it short.

Which aspects of time do you watch out for when writing documentation? Feel free to leave a comment.

Getting sequences right

The M*A*S*H episode “The Army-Navy Game” illustrates the importance of getting sequences right in technical writing. Blake and Trapper John are trying to defuse a bomb:

LT. COL. HENRY BLAKE (reading instructions)
And carefully cut the wires leading to the clockwork fuse at the head.

TRAPPER JOHN (cuts the wires)

LT. COL. HENRY BLAKE
But first, remove the fuse.

What can tech writers learn from history?

Histories … can reflect on how technology led the field [of technical communication] to this point, … provide a springboard for predicting how technology might affect the field in the years to come, [and help us] make informed decisions about the future…

This is Saul Carliner‘s claim in his concise, yet comprehensive historical essay called, “Computers and Technical Communication in the 21st Century”. I’ll summarize his argument, respond and cite some academic responses.

The essay appeared last November in Rachel Spilka’s Digital Literacy for Technical Communication: 21st Century Theory and Practice, a book that addresses students, educators and practitioners of technical communication (TC) alike.

Carliner tells the history in two parallel strands, first how TC evolved in a large IT company (IBM), and then how technological developments changed the TC workplace. Telling the histories one after the other makes for some redundancy; I’ll merge the strands into one in my summary.

Carliner’s argument

Explaining functions and features to professionals was the main task of TC around 1980. Technical writers were hired either for their technical expertise or for their writing skills.

TC centered on users and their tasks throughout the 80s, when the range of applications and audience widened. The first desktop publishing applications enabled writers to get more involved in the production of their deliverables.

With the rise of PCs in the 90s, three trends drove changes in TC:

• The “GUI revolution”, which presented applications in windows-like desktops, further widened the audience for documentation. Users required task-based documentation for more purposes than before. At the same time, technical communicators could address users in new formats, from searchable online help to self-guided e-learning courses.
• The web and browser technologies have moved publication and delivery of documentation online, where text and images were easier, faster and cheaper to distribute.
• Standards and standard-like formats, such as WinHelp, FrameMaker, HTML, PDF and XML established common interfaces and practices. They ensured that even complex applications could distribute contents and services reliably.

Technical communicators responded to these trends with a new role: User experience experts design interfaces and interactions, for which technical writers structure and define documentation contents.

In the last few years, the three trends have further diversified the tasks and products of technical communicators in both roles. For example, films and sound have become as easy and fast to distribute as text and images. The DITA standard has enhanced the XML standard for TC purposes. Two additional developments shape TC significantly:

• The two-way Web 2.0 has evolved more recently and encourages users to not only consume, but create contents as well in virtually all documentation formats.
• Content management systems support the continuous production and publication of content that can be dynamic and user-specific.

My response

I appreciate Carliner’s grasp which admirably summarizes and structures decades of volatile developments in IT. I was surprised to learn that several technologies that I had taken for granted had been introduced shortly before I started in TC.

It’s interesting to see that some early practices still stick around, for better or worse: We’re still debating whether technical or language skills are more valuable. Carliner’s history is one of evolution, not of discrete stages where a new stage replaces the previous one. So the old is not necessarily bad, the new is not better just because it’s new (and Carliner doesn’t claim it is).

One of his premises seems to need a qualifier: I think that technological developments as such don’t drive the evolution of TC. This idea of “build it, and they will come” has been proven wrong in the dot com bust (which Carliner mentions). Whether or not any technology prevails to change the TC workplace depends on several factors, including its usefulness and efficiency, the marketing and market share.

Given such a complex motivation of changes in TC, I can’t quite imagine how looking at technology might shape the field and help us “make informed decisions in the future.” I think it’s more useful to keep an eye on user benefits and how they’re embodied in use cases and services.

Academic opinions

Syracuse University has used Carliner’s text in their CCR 760 class “TC in the Digital Age” that is part of their Composition and Cultural Rhetoric PhD program. Teacher Mike Frasciello points out that many more roles produce documentation than just technical writers:

In many ways, the activity of producing information products was decentralized and moved out of documentation groups. Business analysts were writing and publishing use-case studies. Programmers were writing help statements as conditional code statements. Quality analysts were writing FAQs and user documentation. These individuals were not recognized as technical communicators…

And Missy, a student, argues that technical communicators’ improved skills to produce their own deliverables is quickly taken for granted and therefore seems to lose value. She makes a comparison to

Deborah Brandt’s Literacy in American Lives when she talks about how increasing access to education and higher rates of literacy are seized (that may not be the right word) by corporate/economic interests that begin to expect (or demand) higher levels of literacy while the way those literacies are valued begins to decrease. So, as Carliner demonstrates when he talks about the kinds of technical skills technical communicators are expected to come into the workplace with, being able to use various kinds of software or internet technologies becomes a necessary prerequisite for technical communication jobs rather than something that is valued as specialized knowledge.

Your turn

What do you think? Does technology drive change in our field? Or is it customers and business? Or is it pointless to separate the factors? And how useful is history as our crystal ball? Feel free to leave a comment…

How important is your manager?

… pick your manager first. A great manager will negate most other work problems, whereas an awful manager will negate most other work pleasures.

I found this in a post on Scott Berkun’s blog, and it is oh so true! It’s the single most important factor in my satisfaction with a job. Nothing else shapes my memory and my judgment of a past job as much.

A couple of caveats apply to tech writers:

• Unless you’re working in a dedicated documentation department, even a good manager may still need to learn a thing or two about good documentation. You can spot a good manager if he’s willing to listen, but still keeps you on your toes.
• I guess few tech writers actually get to pick their manager. Yet all else being equal, go for the better manager, when choosing between two departments – or, hey, two job offers…

What do you think? How important is your manager to your satisfaction and sense of progress in a job?

Portable apps for tech writers IV: Wrangling files and PDFs

By now you maybe know that I’m fond of portable apps. That I use them to write, take screenshots and look up stuff in dictionaries with them. But wait: There’s more! No matter how well I manage my contents and architect my information, sometimes files just go unwieldy on me. That’s when they come in:

My favorite apps to wrangle files

Now where’s that file again? Baregrep finds files by name, very quickly – much faster than Windows’ file explorer! And it finds text within ASCII files, again very quickly. It’s my favorite tool to find elusive entries in .txt files or help contents in .html or .xml files. Unix users will recognize the name: This is really a “bare” grep that also masters regular expressions. You’ll have to live with a nag screen upon startup, but, hey: It’s free…

Uh, how come there’s so many of them? Easy Duplicate File Finder finds, uhm: duplicate files. It compares not just file name and size, but contents, too! So when your “to read” folder has gotten too big again, it’ll point out that white paper which you’ve downloaded twice – with different names… It’s also great to clear out project directories where you may have created countless copies of files.

… and now without the spaces. Bulk Rename Utility comes recommended by reader JosephK. He writes: “Bulkrenaming of files with regexp expressions can be done with BulkRename. The interface takes some getting used to.”

For intrepid explorers. XYplorerFree is my portable file explorer of choice – and it’s not even double-pane. But I like it for its comprehensive file-finding and various display options, so I don’t mind that the last free version is almost 4 years old. If you want dual-pane explorers, try freeCommander and UltraExplorer, both of which rank highly. Or try some of the other file explorers in The Portable Freeware Collection.

Portable zipping. PeaZip is my archiving/compression tool of choice. It claims to handle 118 file types. At least, I’ve never had an archive type it couldn’t open. Be sure to grab the “PeaZip portable_standalone” package.

In sync. DSynchronize is a reliable file synchronizer with a straight-forward interface. You can preview what files will be added, deleted or overwritten before committing the changes. You can also opt to sync only newer files or to sync both sides. If you don’t like this one, try Toucan which is a bit fancier and also available from portableapps.com. (Remember that portableapps.com versions don’t require the portableapps.com platform – you can just point their installers anywhere…)

…got til it’s gone. CyberShredder removes files. For good. It overwrites them, up to 7 times. This can be useful when you want to be sure your files are not on the machine after you leave.

Going truly portable with PDFs

It’s a bit ironic that it’s called “Portable Document Format”, when it’s so difficult to modify PDFs – if it wasn’t for portable PDF editor PDFTK Builder. It lets you reorder, delete and duplicate pages in a PDF file and merge pages from multiple PDFs. You can also split a PDF into files with one page each. (Splitting and merging a subset, however, often gives you much larger file than the source, so it’s more like a first-aid kit for emergency surgery.) You can also rotate and stamp pages and protect your documents with passwords to read or change the documents.

If you just want to read PDFs on a fast, portable reader, I recommend Foxit Reader. Others prefer the even smaller Sumatra.

What tools do you use to wrangle files on the go? Feel free to leave a comment.